How to use Markdown and MkDocs

This documentation is built using Markdown and MkDocs. This page is a guide to get you started contributing.

What is Markdown

Markdown is a lightweight markup language used to format text in a simple and readable way. It uses plain-text syntax to define elements like headings, lists, links, and emphasis (e.g., bold, italic). Markdown is commonly used in documentation, blogging platforms, and version control systems like GitHub because it is easy to write and converts seamlessly into HTML for web display. -ChatGPT

Markdown files are often recognizable by their .md and rarely .markdown file extensions.

Basic Syntax

Bold and Italics

To make bold text, surround your text with double asterisks:

**This text will be bolded**

This text will be bolded

For italics, use a single asterisk:

*This text will be italicized*

This text will be italicized

These can be combined:

***This text will be bold and italic***

This text will be bold and italic

Headings

Headings are denoted using # at the beginning of a line. The number of # determines the depth of the header:

Input	Render
# Heading 1	Heading 1
## Heading 2	Heading 2
### Heading 3	Heading 3
#### Heading 4	Heading 4
##### Heading 5	Heading 5

Links

To add links, use the following syntax:

[The text that will be displayed](The link to follow)

[A link to example.org](https://example.org/)

A link to example.org

Images

The syntax to add images is almost the same as links. Alt text is the text used by accessibility readers. It should therefore be descriptive rather than a title.



Code Blocks

Code blocks in Markdown can be created using triple backticks (```). You can specify the language for syntax highlighting by adding the language name after the opening backticks. Here is an example of a code block in Python:

```python

def hello_world():

print("Hello, world!")

```

def hello_world():
    print("Hello, world!")

You can also create inline code by wrapping text in single backticks (`). For example, `print("Hello, world!")` renders as print("Hello, world!").

Advanced Syntax

Markdown's strength is in the simplicity of writing, but that sometimes comes back to bite us when trying to do something a little more complicated. Luckily, most Markdown renderers accept some HTML in Markdown files. This is the case with MkDocs and GitHub. HTML should only be used as necessary.

Comments

In Markdown, there is no built-in syntax for comments. However, you can use HTML comments to add notes or comments that will not be rendered in the final output. Here is an example:

<!-- This is a comment and will not be rendered in the final output -->

Images in HTML

Images are impossible to scale or render next to text. Using the HTML <img> tag, it is possible to customize your image's behavior. Here is an example of an image that is scaled and displayed to the right. Keep in mind that images can't be rendered above the position of the <img> tag:

<img src="../img/favicon.png" alt="A square version of the autotech logo. It is used as a favicon for the site" title="A UST-10lx Lidar" width="200" align="right"/>

Admonitions

Admonitions are a way to highlight important information in your documentation. MkDocs supports several types of admonitions, such as notes, warnings/caution, danger, and tips/hint. Here is an example of how to use them:

!!! note
    This is a note admonition.

!!! warning
    This is a warning admonition.

Using MkDocs

For full documentation, visit mkdocs.org.

Commands

• mkdocs serve - Start the live-reloading docs server. It should now be accessible at 127.0.0.1:8000 on your machine.
• mkdocs gh-deploy - Build the documentation site on the gh-pages branch of your repository.

Project Layout

mkdocs.yml    ## The configuration file.
docs/
    index.md  ## The documentation homepage.
    ...       ## Other markdown pages, images, and other files.
    img/
        favicon.png ## The icon that appears on the browser tab.
        ... other images

Using GitHub Pages

Navigate to the repository, then to settings/pages. Using the drop-down menus, select "Deploy from branch" for source and "gh-pages" and "/root" for branch.