[Feedback/Discussion] CoFH World Docs - Examples

[sustained]

Apparently contributions are welcome according to KingLemming on Discord, so I started working on a little something.

I just wanted to open an issue early on so that discussion can take place and feedback can be gathered and such.

If there's anything about the layout/design you'd change then please let me know.

Also if you disagree with the decision to have one example per page on an Examples page and several on each Feature and Distribution Type page then also speak up.

---

Legend

• ❗ It's trying to get your attention, probably means I want you to look at it.
  ⏳ In-progress.
• ⏸️ On hold.

Issues

1. ❗ Currently several extra JS and CSS files are being included globally. This is bad:tm: and needs to change. I am proposing the addition of a feature which would allow the sub-layouts to tell the main layout to include extra JS/CSS. That way these extra includes could at least be relegated to the docs.html layout. Which is a fair bit better. Suggestions welcome.

Todo List

• Create example-related partials/templates.
• Create example Jekyll collections.
• Create dummy files for every feature type and distribution type.
• Render the collections on the examples page.
• Work on layout/design for the examples that are on the feature/dist. type pages.
• ⏸️ Finalise layout/design - give feedback, please.
• ⏳ Create at least one example for each thing.
  1. Create, test and upload (Gist, perhaps?) the JSON file.
  2. Take at least 2-3 screenshots.
  3. Write the description.

Code

https://github.com/sustained/cofh.github.io/tree/cofh-world-docs-improvements

[Tonius]

Adding a global examples page as an overview of the mod along with the more specific examples on other pages is a good idea, I like it.

I would refrain from using tabs, or at least make the screenshots visible by default. Seeing pictures is always nice when browsing through a page. Also, instead of scrolling down and clicking tabs, the reader only has to scroll down.

Here's my idea:

Cluster

This is a very nice description of this example.

[Picture 1] [Picture 2] [Picture 3] (A row of thumbnails)

(A code block that is collapsed or only shows the first 5-10 lines by default)

This way, everything except the code itself is always visible, making the examples easier to browse through.

I like the idea of only including CSS and JS files where needed. However, that should probably be in a separate issue.

[sustained]

Adding a global examples page as an overview of the mod along with the more specific examples on other pages is a good idea, I like it.

Good to hear, I'll keep it like that then!

I would refrain from using tabs, or at least make the screenshots visible by default. Seeing pictures is always nice when browsing through a page. Also, instead of scrolling down and clicking tabs, the reader only has to scroll down.

True, the screenshots should probably be visible by default but the code definitely should be hidden in my opinion otherwise the page is going to be very very vertical, even with code examples limited to only displaying 10 lines.

I like the idea of only including CSS and JS files where needed. However, that should probably be in a separate issue.

Okay, for now I'll not worry about the extra global CSS/JS and we can look at that issue later.

---

Thanks for the feedback.

[sustained]

Second attempt.

[Tonius]

I like this much better. A couple notes:

• I don't think the headers 'Description' and 'Screenshots' are really necessary. Removing them should free up some more space.
• Showing code blocks is more convenient than a download button in my opinion, because you can easily copy-paste parts of the code that way. Maybe a code block that is completely collapsed by default with a download link/button next to it?

[sustained]

Would you be okay with e.g. a Github Gist embed for showing the code?

Otherwise I'm not really sure how to implement it.

EDIT:

The main issue with that being I don't think it's possible for me to give you guys permission to edit my gists.

I think I have an idea how I'd implement it without using embedded gists but it's going to be a lot of messing around/much more difficult than embeds.

[sustained]

Third attempt.

[sustained]

I'm pretty happy with my progress so far.

I've got it to the point where the individual feature/distribution types use the same templates even.

So, for example, in /docs/cofh-world/world-generator-configuration/feature-types/lake.md (as with every other relevant file) I have added this:

{% include examples.html group="lake" primary=false %}

The only thing that changes for each is the group. of course.

Even the main/master examples page uses this same include so it's all very nice and centralised. The only difference on the main examples page is that primary is set to true and it uses type="feature" and type="distribution" instead of group.

I am brand new to Jekyll and Liquid but I'm pretty happy with my implementation.

Also, since I've updated all the pages, now we get an automatic nice little thing:

HINT: It's the little notice under examples. And it naturally goes away if you add examples for that thing automatically, of course.

---

At this point I'm awaiting feedback on:

• the decision to use Github Gist embeds.
• the third iteration of the layout (the examples on the feature/distribution type pages themselves look identical.

Also there are a few issues:

1. I basically added some code so that we can detect if JS is disabled. The body has a class of cofh-no-js by default and it is removed as soon as possible in cofh.js in the jQuery ready callback. But for some reason it seems to happen about 1500-2000ms after the page has finished loading and I honestly can't figure out what is causing the delay. The code is there so that the show/hide code buttons can be hidden when JS is disabled, in case you were wondering.
2. Another minor issue is that some CSS of yours #cofh-docs-content a[href^="http"] { color: #4b97d8; } was messing with my UIKit buttons, so I had to override it with !important because I'm not really sure why that CSS is targeting things like it is and why it's making them blue in that case and didn't want to mess with it (for instance - why does it match only http and not https?)
3. I guess the only remaining issue is that since I'm using Github Gist for the code examples - the code examples are on my Github account and there's no way afaict for me to give you access to them. Yes, we could store them in a/this repository but then the issue becomes how do we trigger a download of the file? It's not possible.
4. I am not really sure how to implement the code showing/hiding in a nice way.

In any case, all the code has been pushed to my branch if you did want to take a look at it.

@Tonius

[sustained]

As I said, there is no difference in the layout/template for the feature/distribution type pages but just for the sake of completeness:

(Yes, it says cave_example.json because the file was copy-pasted quickly to demonstrate how it would look!)

---

And just to prevent you from having to dive through my code/for the sake of even more completeness, this is basically what an example definition file looks like:

---
link:
  docs: /docs/cofh-world/world-generator-configuration/feature-types/boulder/
  code:
    embed: $LINK_TO_GITHUB_GIST
    download: $LINK_TO_GITHUB_GIST
type: feature
group: boulder
title: Boulder Example
primary: false
images:
  -
    href: foo.png
    title: I am the first example.
  -
    href: bar.png
    title: I am the second example.
---

This is an example of spawning boulders.

[Tonius]

I was a bit unsure about the Gist embeds, but they do look quite nice. I would suggest putting the gists in the CoFH group, but it looks like that's not possible. Maybe we could make a shared account for them, or something.

The easiest alternative to Gists would be to just add the code in <pre> blocks in the docs; either without a download button or by also putting copies of the code in separate files (putting the same code in two different places).

• I think it would be better if the code visibility toggle was right above the code blocks, instead of being off to the side. As for the implementation, I could take a look at that if I get some time. If not, it could just be added later.
• Download buttons seem redundant when using gists because they already include links to the (raw) gists themselves.
• With the above two points in mind, only the documentation link button remains. Perhaps that could be put somewhere else too, maybe at the bottom of an example or at the end of the description text. This would remove the whitespace at the top of the examples.
• The css that colors links is so that links to external wikis have a slightly different color in the docs. Here's an example. It might be a bit too subtle though. To prevent conflicts with buttons, you could change the selector to: #cofh-docs-content a:not(.uk-button)[href^="http"]

[sustained]

• The gists do look pretty good, don't they? Well, don't forget that gists are repositories that can be forked and cloned. So you could absolutely contribute to them, it's just not as streamlined a process UI-wise as collaborating on a repository. I'm happy to make a shared account in any case.
• Yep, I had thought about just including them in the example files in <code> and <pre> but decided against it, primarily because we wanted the screenshots above the code.
• Yeah, the show/hide code thing would probably be better further down - I'll do that. I just wasn't sure how to make it work with UIKit, specifically. I could absolutely get it working with some custom jQuery but if UIKit has a way to do it then I felt that we should make use of it.
• True however "view raw" does NOT trigger a download. They would be required to click "view raw" THEN right click THEN "save as" THEN choose a directory/name. Now multiple that by each example... for someone who is browsing many at once. I just figured, why create that much work for a user?
• Yeah, the whitespace is not the most sightly thing. It looked fine when we had headers but now it looks strange. I'll try moving the button down.
• Okay, it did occur to me to add a :not() to your CSS but as I said I had no idea why the CSS was even there and I didn't want to accidentally break anything. I'll do that.

[sustained]

I decided to make it so you can choose whether to use a Github Gist or whether to include the code in the example itself, on a per example basis. I also experimented some more with the layout.

I am using Rouge for syntax highlighting, I believe it's the default anyway with Jekyll.

Below you can see both (gist and non-gist) in one image.

At this point I am going to stop messing with the layout so much, it's just a single file that needs to change and it can be done later, at any time, by anyone.

I am going to move on to actually compiling all of the examples now: writing the JSON files, writing the descriptions and taking the screenshots. 😄

[sustained]

Update on main examples progress (each includes >= 3 images + example JSON file):