CODEWITHSUNDEEP
jekyll
Jim
Jim

Reputation: 2828

Jekyll Docs folder

Im my Jekyll website I need to create an documentation section similar to Original website. However I am not sure how the Docs sections renders. For example, the docs folder, which is located in site root, is filled with documentation .md files. This folder doesn't inculde any index.html file responsible for Layouting of website. The link to that folder is 

 <a href="{{ site.url }}/docs/home/">Doc<span class="show-on-mobiles">s</span><span class="hide-on-mobiles">Documentation</span></a>

Could someone shed a light on how this section is rendering?

Upvotes: 2

Views: 443

Answers (1)

Christian Specht
Christian Specht

Reputation: 36451

The docs folder includes an index.md, which is rendered as index.html in the final site.

If you look at the YAML front matter of index.md, you'll see this:

---
layout: docs
title: Welcome
next_section: quickstart
permalink: /docs/home/
---

The permalink: /docs/home/ line sets the final URL to {{ site.url }}/docs/home/, even though the actual file is in the /docs folder and the /docs/home folder doesn't even exist.
(for more info about the permalink setting, see Predefined Global Variables in the docs)

So that's where the URL comes from.

Concerning the list of documentation topics (the sidebar on the right):

The YAML front matter of index.md (see above), also contains the line layout: docs.
This refers to /_layouts/docs.html, a layout file.

Inside the layout file, there's the line {% include docs_contents.html %}, which refers to _includes/docs_contents.html, an include file, which contains the following code:

{% for section in site.data.docs %}
<h4>{{ section.title }}</h4>
{% include docs_ul.html items=section.docs %}
{% endfor %}

site.data.docs (in the first line) refers to /_data/docs.yml, a YAML data file.
It looks like this (shortened):

- title: Getting Started
  docs:
  - home
  - quickstart
  - installation
  - usage
  - structure
  - configuration

- title: Your Content
  docs:
  - frontmatter
  - posts
  - drafts
  - pages
  - variables
  - datafiles
  - assets
  - migrations

The code inside docs_contents.html loops through the items in the data file, displays the title values ("Getting Started", "Your Content"...) and then includes another include file /_includes/docs_ul.html, passing the list of docs from the data file.

This second include file loops through the list of docs, and does the following for each one:

Step 1:

{% assign item_url = item | prepend:'/docs/' | append:'/' %}

This builds the URL of the page based on the list item. For example, quickstart becomes /docs/quickstart/.

Step 2:

{% if item_url == page.url %}
  {% assign c = 'current' %}
{% else %}
  {% assign c = '' %}
{% endif %}

This marks the current page (used in the next step) by checking if the URL created in the previous step is equal to the URL of the current page.

Step 3:

{% for p in site.pages %}
  {% if p.url == item_url %}
    <li class="{{ c }}"><a href="{{ site.url }}{{ p.url }}">{{ p.title }}</a></li>
  {% endif %}
{% endfor %}

This loops all pages in the whole site, until it finds the page with the URL created in the first step.
(to make sure that the URL is equal, all Markdown files in the docs folder have set a permalink in the front-matter, for example permalink: /docs/quickstart/ in quickstart.md)

Then, it outputs a <li> with a link to the page, using the title from the respective Markdown file as the link text.
Plus, the class of the <li> is set to current if it's the current page (see step 2), so the current pae is highlighted in the list:

current page

Upvotes: 2

Related Questions