Documentation on how to build navigation #5698

Open
wants to merge 6 commits into
from

Projects

None yet

5 participants

@tomjohnson1492
Contributor
tomjohnson1492 commented Dec 27, 2016 edited

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.

@jekyll/documentation

@tomjohnson1492 tomjohnson1492 Documentation on how to build navigation
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](http://jekyllrb.com/docs/datafiles/#the-data-folder). 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](jekyll/jekyll-help#266).)  The documentation on navigation would fit well into the Jekyll docs.
845580a
@ashmaroli
Contributor

@DirtyF How about hosting all "how to.." stuff on another document entirely? (or a subdomain e.g. tips.jekyllrb.com?)

/cc @parkr

@tomjohnson1492
Contributor

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.

@ashmaroli
Contributor

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. http://tips.jekyllrb.com was only a suggestion. In theory it will work because tips will be a subdomain of jekyllrb.com, no way related to http://jekyll.tips. But should the idea be considered, we could think of using a different subdomain entirely to avoid confusion with the latter site.

IMO, jekyllrb.com being official documentation should not disseminate tutorials.

@pathawks
Member

What I'm proposing is that all documentation related to non-basic customization of Jekyll be moved to a separate document

I disagree that making it more difficult to find or contribute to documentation would solve any problem.

@tomjohnson1492
Contributor

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.

@ashmaroli
Contributor

👍 to more tutorials.. I would just like them all collected under a single dedicated document/sub-domain.
👍 to _tutorials collection folder. It addresses my point with minimal interference.

@tomjohnson1492
Contributor

Do you want me to create the collection for this? I can. I just wasn't sure if you were waiting for me to do that.

tomjohnson1492 added some commits Dec 27, 2016
@tomjohnson1492 @DirtyF tomjohnson1492 Include navigation page in doc list
Include the navigation page in the sidebar doc list.
972dc8c
@tomjohnson1492 @DirtyF tomjohnson1492 Added link to new navigation page
This just links to the new page I added about navigation.
75c40ed
@DirtyF DirtyF added the documentation label Jan 2, 2017
@ashmaroli
  • contents of HTML blocks, CSS and liquid blocks need to be indented consistently.
  • move styles to our sass partial.
docs/_docs/navigation.md
+permalink: /docs/navigation
+---
+
+<style>
@ashmaroli
ashmaroli Jan 2, 2017 Contributor

<style> blocks should be moved to an external stylesheet.. this would allow the use of same styles for future tutorials.

@tomjohnson1492
tomjohnson1492 Jan 4, 2017 Contributor

updated

docs/_docs/navigation.md
+
+<style>
+.result {
+border: 1px solid yellow;
@ashmaroli
ashmaroli Jan 2, 2017 Contributor

indentation required for better readability

@tomjohnson1492
tomjohnson1492 Jan 4, 2017 Contributor

updated

docs/_docs/navigation.md
+{% raw %}<h2>{{ site.data.samplelist.docs_list_title }}</h2>
+<ul>
+ {% for item in site.data.samplelist.docs %}
+ <li><a href="{{ item.url }}" alt="{{ item.title }}">{{ item.title }}</a></li>
@ashmaroli
ashmaroli Jan 2, 2017 Contributor

contents of liquid blocks are indented as well..

<ul>
  {% for item in site.data.samplelist.docs %}
    <li><a href="{{ item.url }}" alt="{{ item.title }}">{{ item.title }}</a></li>
  {% endfor %}
</ul>
@tomjohnson1492
tomjohnson1492 Jan 4, 2017 Contributor

updated

docs/_docs/navigation.md
+<li><a href="configuration.html" alt="Configuration">Configuration</a></li>
+<li><a href="deployment.html" alt="Deployment">Deployment</a></li>
+</ul>
+</div>
@ashmaroli
ashmaroli Jan 2, 2017 Contributor

indentation required..

@tomjohnson1492
tomjohnson1492 Jan 4, 2017 Contributor

updated

docs/_docs/navigation.md
+{% for item in doclist %}
+<li><a href="{{ item.url }}" alt="{{ item.title }}">{{ item.title }}</a></li>
+{% endfor %}{% endraw %}
+```
@ashmaroli
ashmaroli Jan 2, 2017 Contributor

indentation required..

@tomjohnson1492
tomjohnson1492 Jan 4, 2017 Contributor

updated

@tomjoht tomjoht Made updates with indentation
5166ead
@tomjohnson1492
Contributor

I made the necessary updates around indentation. Submitting for re-review.

docs/_docs/navigation.md
-<li><a href="{{ item.url }}">{{ item.title }}</a></li>
-{% endfor %}
+ {% for item in site.data.samplelist[page.sidebar] %}
+ <li><a href="{{ item.url }}">{{ item.title }}</a></li>
@ashmaroli
ashmaroli Jan 6, 2017 Contributor

requires additional indentation here.. 😉

@tomjohnson1492
tomjohnson1492 Jan 13, 2017 Contributor

updated

docs/_docs/navigation.md
-<li class="{% if item.url == page.url %}active{% endif %}">
-<a href="{{ item.url }}">{{ item.title }}</a></li>
+ <li class="{% if item.url == page.url %}active{% endif %}">
+ <a href="{{ item.url }}">{{ item.title }}</a></li>
@ashmaroli
ashmaroli Jan 6, 2017 Contributor
  • the anchor tag is nested.. so would need to be indented..
  • the closing list-item tag on a new-line..
@tomjohnson1492
tomjohnson1492 Jan 13, 2017 Contributor

updated

+
+**Result**
+
+<style>
@ashmaroli
ashmaroli Jan 6, 2017 Contributor

<style> => External CSS

@DirtyF

This should cover most use cases 😅

Just a few comments.

@@ -150,3 +150,5 @@ author: dave
{% endraw %}
```
+
@DirtyF
DirtyF Jan 6, 2017 edited Member

I would put this in an info section:

If your Jekyll site has a lot of pages, such as with documentation websites, we got you covered with some detailed examples on [how to build robust navigation for your site](..navigation). {: .note .info }

docs/_docs/navigation.md
+
+<div class="result">
+ <ul>
+ <li><a href="introduction.html">Introduction</a></li>
@DirtyF
DirtyF Jan 6, 2017 Member

All these clickable links will generate 404 errors 😭

Shouldn't we use # in href for all examples here?

@tomjohnson1492
tomjohnson1492 Jan 13, 2017 Contributor

updated

docs/_docs/navigation.md
+{% for cat in mydocs %}
+<h2>{{ cat.name | capitalize }}</h2>
+ <ul>
+ {% assign items = cat.items | sort: 'weight' %}
@DirtyF
DirtyF Jan 6, 2017 Member

s/weight/order

@tomjohnson1492
tomjohnson1492 Jan 13, 2017 Contributor

updated

@@ -1031,3 +1031,11 @@ code.output {
clip: rect(0, 0, 0, 0);
border: 0;
}
+
+.result {
+ border: 1px solid yellow;
@DirtyF
DirtyF Jan 6, 2017 Member

I'd rather simply apply highlight for now. We can discuss style in a separate PR.

result-styles

@tomjohnson1492
tomjohnson1492 Jan 9, 2017 Contributor

Thanks for the comments. I'll make the updates in a couple of days (I'm finishing up some presentations).

@tomjohnson1492
tomjohnson1492 Jan 13, 2017 Contributor

updated, but i did leave the padding style b/c without it, the text is right against the line.

@ashmaroli
Contributor

Some more ideas:

  • Collect all tutorials under a new category: tutorials
  • Like how our release news-items are published, allow author to have their name displayed. (optional: link to their blog/website)

/cc @DirtyF, @pathawks

tomjoht added some commits Jan 13, 2017
@tomjoht tomjoht made updates as requested from latest review 7efeb3d
@tomjoht tomjoht making edits from reviews
6d9633e
@tomjohnson1492
Contributor

I made the updates as noted in the reviews. Submitting for review to merge. Thanks, and sorry for my delay in getting to this.

@tomjohnson1492
Contributor

@ashmaroli We talked about making tutorials a collection and putting them into another section. I'm guessing I should make that change, right? This will involve me editing the config file and adding more modifications in the nav somewhere.

@ashmaroli
Contributor

I would like that. But I'll leave the making-the-executive-decisions to @DirtyF 😃

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment