1denglei / static_docs_deprecated

How to edit Husarion Docs

Basics

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

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>

The gallery-6 means 6 images in row. If necessary, also the gallery-2, gallery-3 etc. can be implemented.

Videos

From Vimeo:

<div align="center">
<iframe src="https://player.vimeo.com/video/225576807" width="427" height="240" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
</div>

From Youtube:

<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.

For Tutorials:

Level	ToC level	Syntax
1	1. Article	# Article # - must be consistent with filename (article.md)*
2	1.1. Chapter	## Chapter ##
3	Subchapter	### Subchapter ###

For Manuals:

Level	ToC level	Syntax
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: tutorial-for-core2.md.