Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Documentation on how to build navigation #5698
I added a documentation page on how to build navigation for your site. This topic is primarily intended for users who have a lot of pages on their site (such as for documentation websites), and want to build a more robust sidebar navigation.
Jekyll combines Liquid with YAML in interesting ways that aren't really documented clearly in the existing docs, except for a brief reference here. You can read about Liquid on Shopify and YAML in YAML's docs, but exactly how you store YAML files in a Jekyll project and iterate through them using Liquid loops and filters to generate lists of pages is something that isn't clear to a lot of people. (You can see origins of these questions in previous help issues.) The documentation on navigation would fit well into the Jekyll docs.
Are you proposing that all documentation be moved into a subdomain? Or just some types of documentation?
If it's just some types of documentation, my suggestion is that rather than fragmenting the documentation into different domains, we instead create an Advanced page that simply lists the advanced tutorials.
I get that we probably don't want Jekyll's documentation to seem too complicated. (All product managers want their product to seem simple.) But the result is often a paradox. The more "simple" we try to make something by removing documentation, the harder it can become for people to use the product. As soon as people get passed the first step of installing Jekyll, they're confused at how to go to the next step.
The solution to providing simple instructions for novice users and advanced instructions for advanced users is to separate the info out a bit. Put the advanced content into an advanced area. This is why I proposed adding a link to the navigation document from http://jekyllrb.com/docs/datafiles/. The datafiles doc starts out easy, and when you want to do something more, you transition to more advanced info (progressive disclosure).
But maybe I'm misinterpreting the proposal here. Maybe the subdomain idea is to facilitate something else altogether, such as simplifying merge updates? Would decoupling docs from the other Jekyll code make it easier to deploy updates?
Re tips in the subdomain, there's already http://jekyll.tips/, so that wouldn't work. (Actually, I'd love to see Mike's info be merged with the existing Jekyll doc. I don't know why that's separate in the first place. His tutorials and info are golden.)
The most logical alternative for a subdomain is docs.jekyllrb.com.
What I'm proposing is that all documentation related to non-basic customization of Jekyll be moved to a separate document or subdomain ( new repo ) by itself.
I think it's a good idea to have different areas of documentation. I can see value in having a section designated for tutorials, another section designated for reference, another for getting started. And I can see how this topic on implementing navigation would fit into a tutorials section.
But as far as shifting around the different types of content onto different subdomains, I'm not a fan of that. It will make linking more difficult, as well as potentially create confusion among users.
How about just adding a link to "Tutorials" in the sidebar, and then on that page, add a link to "Implementing Navigation." Or create a _tutorials collection and put them there. Then they could be under jekyllrb.com/tutorials instead of jekyllrb.com/docs. I like that idea.
I have a few other tutorials brewing in the back of my mind. For example, implementing media RSS feeds, converting an HTML theme into a jekyll site, implementing translation, validating links, and more. All of these topics could comfortably fit into a Tutorials collection.
Really, users don't care as long as they can find the information and it answers their question. Good documentation has a mix of reference, tutorials, how-to topics, and more. Think about it -- the foundation of all developer documentation is a "Hello World" tutorial.
- contents of HTML blocks, CSS and liquid blocks need to be indented consistently.
- move styles to our sass partial.
This should cover most use cases
Just a few comments.
@tomjohnson1492 If you're up for it, yes! You can use a lot of the existing templates for
I made an update here that you'll want to look at. Following @parkr's green-light, I added a new collection called tutorials and made it function similar to docs. I also added an overview page to the Tutorials section (in addition to the navigation topic that already exists). I think this section will help create a space for a wider number of community contributions -- I can already think of about 5 tutorials I want to add here.
This was referenced
Jan 30, 2017
referenced this pull request
Feb 11, 2017
I had a review here from over a week ago and forgot to submit it. I'm sorry! It's not a complete review, but just some nit-picks.
@parkr I made updates from your review. I moved the "Tutorials" link to the help page and removed the yellow border around the result content.
I'd really like to get this PR merged so that I can add other tutorials here as well. Let me know if I need to do anything else to speed this along. Thanks.