Documentation - How to edit
The Documentation project is the project tasked with creating and managing a documentation website for the Describe Markup Language, the Listiary wiki, and all the related - child or satellite projects. The result is the very same documentation you are reading at the moment - originally hosted at documentation.listiary.net.
In this article, we will see how to add, edit and publish articles to the documentation website.
1. Turn text article drafts to markdown, suitable for Jekyll
The first step would be to prepare a text draft of the article - refine it, spell check it, etc. But once this is done, the next step is to turn the article to a suitable markdown.
To turn plain text to a markdown syntax, suitable for our project and following our conventions you must simply follow few basic rules:
• Manage new lines strategically and chech for the result with a markdown render-er. Check other articles already done. (Use two spaces after the end of a paragraph. <br> tags can help here too)
• Write links as [link text](https://link-url.com/)
• Write headings with # signs - ### Subtitle or ## Title e.g.
• Escape code with backtick - `.
• Markdown can contain HTML directly. Use HTML spans with style property to colorize and decorate text, when needed
• it can be more reliable than markdown, and is more flexible.
To turn markdown files Jekyll suitable for our project, you must add the Jekyll front matter. It is a text that we add at the beginning of each markdown file. It shall look like this:
---
layout: page
title: Radiowatch - FAQ
permalink: /listiary/radiowatch/faq/
exclude: true
---
2. Build Jekyll documentation
Go to the folder containing the jekyll dir - \DescribeCompiler.jekyll,
Adjust values in _config.yml if needed.
Copy the prepared markdown files/directories to the content subfolder,
Copy the index to the main folder as well, making sure that the permalink on that version is commented - # permalink:,
Run Jekyll
In cmd, cd to the jekyll dir - cd "PATH_HERE\DescribeCompiler.jekyll",
Run bundle install,
Run bundle exec jekyll -v if you want to test,
Run bundle exec jekyll clean,
Run bundle install,
Run bundle exec jekyll serve,
View result
Check result on localhost - http://127.0.0.1:4000/,
Ctrl+V then Y then Y to stop server later;
Check stuff
Check if ruby installed: ruby -v
Check if Jekyll installed: jekyll -v
Install Jekyll:
gem update --system
gem install jekyll bundler
jekyll -v
Commands
jekyll new @website --force
cd @website
bundle exec jekyll serve
bundle exec jekyll serve --draft
Jekyll folder
gem environment - C:\Ruby32-x64\lib\ruby\gems\3.2.0\gems
gems - C:\Ruby32-x64\lib\ruby\gems\3.2.0\gems\jekyll-4.3.3\lib
Ready sites
C:\Users\Viktor Chernev\Desktop\World-Describe\Website\WorldInLists-Documentation\ver_blog
3. Get the HTML version
The \DescribeCompiler.jekyll\_site folder contains the HTML version of the website after serving it in the previous step. We simply copy all the contents to \DescribeCompiler.html, after deleting the contents of the folder.
That is our host-able site. We can go ahead and use FileZilla to upload it, but keep in mind that it won’t work properly as a file:// on a local host, without being served.
I. Modify the minima theme
We will not need to do this every time, but I include it, just in case something goes wrong with our setup, and we need to set up from scratch.
We are applying a few small modifications to the preinstalled minima theme before we use it, and we are doing that by copying some of the sub-folders of the theme to our Jekyll folder, so that they might take precedence for our project but not affect other projects, and also, we don’t loose the changes when we update the minima theme.
A) In the main CSS file, the first media query says - @media screen and (max-width: 600px) { - we want to remove the second part and leave it as @media screen {.
This is the query that makes the navbar into a hamburger button, and by modifying it like that, we make sure it remains a hamburger button for any screen sizes, not only on mobile devices. To do that, we find our installation of the minima theme - which is just a ruby gem, residing in C:\Ruby32-x64\lib\ruby\gems\3.2.0\gems, copy the _sass folder to our project, open the “_layout.scss” file and replace @include media-query($on-palm) with @media screen. We copy the folder to our project so that this version is always loaded from here.
B) We do some modification to the ruby logic in _includes/header.html.
The example below shows that we are using the custom front matter variable exclude to exclude any pages where it is set to true.
We also manually added the links we want included in the nav-bar.
It looks like this:
<div class="trigger">
<a class="page-link" href="/language/how-to-write/">Language Home</a>
<a class="page-link" href="/language/how-to-compile/">Compiler Home</a>
<a class="page-link" href="/language/reference/">Tech Reference</a>
<a class="page-link" href="/language/">About Describe</a>
<a class="page-link" href="/listiary/">About Listiary</a>
<a class="page-link" href="https://library.listiary.com/">Describe Library</a>
<a class="page-link" href="/language/site-map/">Site Map</a></div>
C) Gray header/footer - We want to add style="background-color: #ccc;" CSS in header.html - here <header style="background-color: #ccc;" class="site-header" role="banner"> and here <nav style="background-color: #ccc;" class="site-nav">, and in footer.html - here <footer style="background-color: #ccc;" class="site-footer h-card">.