Open sustained opened 5 years ago
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.
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.
Second attempt.
I like this much better. A couple notes:
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.
Third attempt.
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:
Also there are a few issues:
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.#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?)In any case, all the code has been pushed to my branch if you did want to take a look at it.
@Tonius
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.
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).
#cofh-docs-content a:not(.uk-button)[href^="http"]
<code>
and <pre>
but decided against it, primarily because we wanted the screenshots above the code.: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.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. :smile:
Update on main examples progress (each includes >= 3 images + example JSON file):
Just chiming in to say y'all are great, thanks.
@KingLemming
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
Issues
docs.html
layout. Which is a fair bit better. Suggestions welcome.Todo List
Code
https://github.com/sustained/cofh.github.io/tree/cofh-world-docs-improvements