Introduction
Welcome to this demo (and documentation) of Docster. A Documentation Theme for jekyll.
Here we’ll show you what the theme looks like and how you will use it. Docster makes setting up an organized Documentation a breeze.
It has a sidebar, that is a table of contents and consists of links, that will scroll you to the respective section.
Docster is perfect for really long and complex as well as short and simple Docs.
Set Up
Setting Docster up is super simple. Just like with all jekyll-sites you just need a GitHub account to host it. Docster is independent of any plugins so the only requirement is a jekyll installation to check the result before pushing.
So download this theme, navigate into the folder, open a terminal and type
jekyll serveYou will then be able to see the page at localhost:4000 and make your changes. When you are happy just push them to github in a gh-pages branch and you’re site will be compiled by GitHub for you.
_config.yml
There is very few configuration to be done before you are up and running, still the ones you need to add, are as follows:
In the _config.yml-file:
# name of the docs
name: Docster Documentation
# docs author
author: DigitalMind
# docs version
version: V 1.0All of these infos will be displayed on the top left-hand corner.
Of course you can also go in and change the sass-output-format or change whatever else you want to adjust.
Sass
The styles applied to Docster are very minimal. There are two colors used throughout the site and some syntax highlighting stylesheet.
If you want to change the colors you will find them within the _sass directory in the modules/_color file. If you want to go with something else than green, you might want to change the variable name (and then just do a folder-wide search with the editor to replace. Almost every editor should have this feature).
Other than that feel free to just browse through the code and change things up as you like.
Content
Now for what Docster is all about. The content.
You want to know how all of this works, right?
So Docster makes use of the collections feature, every entry will be written separately and then be compiled into one single HTML file. This ensures that the output is minimal. So in case that you don’t want to publish the documentation online, it has the perfect format to be put within another folder. Like for example the Download Package of a Theme.
Collection Entries
Okay, so the collection is the entries collection. All of your documentation sections will be placed within that folder.
The index file will then go over every one of these and put them together.
There are different ways on how you can take care of the order of the entries, depending on which one you chose, you will either have to work with filenames, or with the number front matter.
If you decide to work with file-names, you will just prefix your file names with numbers.
Section Types
There are three different levels supported, basically four, but the h4 tags will not be included, within the navigation by default. Read on if you want to change that.
Level one
If you want to create one of the main sections, you will need to include the following front matter within your entry:
---
sectionid: UNIQUE-ID
sectionclass: h1
title: TITLE
---If you want your section to have subsections, add
is-parent: yesThe ID is important, because it will be used as the anchor for the scrollToLinks and it is also used within the subsections. So each child needs to tell jekyll what its parent is, before it can be placed correctly.
Level two
A Subsection of a level-2 will look like this
---
sectionid: UNIQUE-ID
sectionclass: h2
title: TITLE
parent-id: UNIQUE-ID-Of-PARENT
---So the parent-id is where you will reference the anchor of the h1 section that’s your subsections parent.
Level 2 sections can have children, the variable to use is the same. To have children add
is-parent: yesLevel three
A Subsection of a level 3 will look like this
---
sectionid: UNIQUE-ID
sectionclass: h3
title: TITLE
parent-id: UNIQUE-ID-Of-PARENT
---So the parent-id is where you will reference the anchor of the h2 section that’s your subsections parent.
Level 3 sections can have children, the variable to use is the same. To have children add
is-parent: yesLevel four
A Subsection of a level 4 will look like this
---
sectionid: UNIQUE-ID
sectionclass: h4
title: TITLE
parent-id: UNIQUE-ID-Of-PARENT
---So the parent-id is where you will reference the anchor of the h3 section that’s your subsections parent.
Level 4 sections can’t have any more children within sections, but you if you add a h5 title, it will still have the numbering.
Proof here
Told ya! (it will not work on h6 though )
Order
Okay, I have touched upon the order before. As I said, you have two options on how to determine the order of your entries.
The choice of how you go about it, is yours. Both ways have pros and cons, that you have to check for yourself.
We went with the front matter version here, but might go with the numbered files on another Docs. So it might just depend on your mood as well.
File Names
The first option is just prefixing all of your files with file names.
So your files might look something like this:
├── 01 intro.md
│
├── 02 set_up.md
│
├── 02-01 config.md
│
├── 02-02 sass.md
│
├── 03 content.md
│
├── 03-01 collection_entries.md
│
├── 03-01-01 section_types.md
│
├── 03-01-01-01 level_one.md
│
├── 03-01-01-02 level_two.md
│
├── 03-01-01-03 level_three.md
│
├── 03-01-01-04 level_four.md
│
└── and so on...Front Matter
For the second version, you define a font matter variable number So to go with the files from before, this is what this method would look like (under the file name, the front matter.)
├── intro.md
│ └── number: 1000
│
├── set_up.md
│ └── number: 2000
│
├── config.md
│ └── number: 2100
│
├── sass.md
│ └── number: 2200
│
├── content.md
│ └── number: 3000
│
├── collection_entries.md
│ └── number: 3100
│
├── section_types.md
│ └── number: 3110
│
├── level_one.md
│ └── number: 3111
│
├── level_two.md
│ └── number: 3112
│
├── level_three.md
│ └── number: 3113
│
├── level_four.md
│ └── number: 3114
│
└── and so on...