How to edit Husarion Docs
This repository contains sources of the documentation that is available as Tutorials and Manuals pages. They are automatically generated from master branch, but before that, the pull reuqests has to be approved by admin. The preview on GitHub can look slightly different than the publicated version.
The sources are written using Markdown. The syntax of Markdown is well-described on the Daring Fireball website. You can also use HTML if Markdown is not enough.
Source text for articles is stored in /src catalog.
Images are stored in /assets/img
Standard Markdown syntax is applicable for images, but there is an additional possibility to create galleries:
<div class="gallery gallery-6"> ![The caption under image](/assets/img/image.png "the description shown after enlarging the image") ![The caption under image 2](/assets/img/image2.png "the description shown after enlarging the image 2") </div>
gallery-6 means 6 images in row. If necessary, also the
gallery-3 etc. can be implemented.
<div align="center"> <iframe src="https://player.vimeo.com/video/225576807" width="427" height="240" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe> </div>
<iframe width="1156" height="560" src="https://www.youtube.com/embed/JkIj5ssHpKw" frameborder="0" gesture="media" allowfullscreen></iframe>
Metadata headers and ToC generation
Each .md file contains the metadata needed for generate HTML pages that are properly referenced to ToC on the left menu, here is an example:
--- title: 'The first step of tutorial' // page title, not critical platform: 'CORE2' // which hardware platform is documented autotoc: true // generate ToC or not? layout: layout.hbs // don't change order: 2 // the order in section (and the number displayed in ToC) ---
The ToC has 3 or 4 levels. It depends on the page.
|1||1. Article||# Article # - must be consistent with filename (article.md)*|
|2||1.1. Chapter||## Chapter ##|
|3||Subchapter||### Subchapter ###|
|1||Section||# Section # - must be consistent with filename (section.md)*|
|2||1. Article||# Article #|
|3||1.1. Chapter||## Chapter ##|
|4||Subchapter||### Subchapter ###|
- Only small letters and hyphens are allowed in filename. If the article name is # Tutorial for CORE2 #, the filename has only small letters and hyphens instead whitespaces: