This guide defines a temporary formatting standard for stal/IX documentation on GitHub.
Used in all documents:
Headings - are created by using one to six # symbols (depending on the required size) before the heading text. # The document title (h1) is written on the first line.
Paragraphs and line breaks - Leave a blank line between lines of text for paragraphs, use <br> at the end of the previous line for line breaks.
Text formatting - italics - *asterisks*; bold - double **asterisks**; combined highlighting - **asterisks and _underscores_**.
Quotes - created with > before quoting text. Used here to mark up a Prerequisites block. If there is no Prerequisites, quote the document description.
Exception: if there are > indeed quotes, mark up Prerequisites as a bulleted list, and the document description as plain text in the first paragraph.
Code and syntax highlighting - enclosed in single backticks for inline code - `code`; enclosed in triple backticks - ``` for code blocks.
Use a language prefix next to the top line of triple backticks for code highlighting, no spaces - ```shell.
Also used:
Lists: regular - each item on a new line, use <br> (e.g. to list links); bulleted - use asterisks * some text.
Links: You can create an inline link by enclosing the link text in brackets.
[stal/IX](https://github.com/stal-ix/ix) stal/IX
Horizontal dividing line - formed by three (or more) hyphens ---. Use it to highlight special text blocks, for example: Exercise. In the text of a document, a block is highlighted by two dividing lines, at the top and bottom, if the block is at the end of the document - by one dividing line at the top.
The documentation is under development and is regularly updated.
All stal/IX documentation is formatted using Markdown. HTML is acceptable if there is no Markdown equivalent or special formatting is required.
stal/IX is written as is, with a lowercase letter, even in a title or at the beginning of a sentence, IX is written in capital letters if IX package manager is meant. stal/IX is written in bold.
A document always begins with a title. The title is placed at the top, on the first line. There are no buttons, shields, banners, quotes or other design or formatting elements above it.
Place under the title:
The sections of the document are designated by headings.
Special text blocks - with horizontal rule.
Headings are created by using one to six # symbols (depending on required size) before the heading text.
# h1 - the largest heading
## h2
### h3
#### h4
##### h5
###### h6 - the smallest heading
The # h1 heading marks the document title on the first line. There can only be one h1 heading per document.
The second-level # h2 heading marks the document sections, if any. Then, use the other heading levels as needed.
Paragraph - leave a blank line between lines of text. Line breaks - use <br> at the end of the previous line.
Important: Markdown Here’s line break rules (two spaces at the end of a line) are not used to avoid removing trailing spaces when the editor is set to do so.
Bold and italic are used:
*asterisks*;**asterisks**;**asterisks and _underscores_**.Required text highlightings:
*Pro tip* italic*Warning* italic*Important* italicBefore quoting text, use the > symbol.
> Quoting text
Quoting text
Here we mark the Prerequisites block as a quote. If the document has no prerequisites, quote the document description.
Exception: if the top of the document text (the first two paragraphs) indeed has quotes, then mark the Prerequisites as a bulleted list, the document description as plain text in the first paragraph.
To embed code or command output in a sentence, use single backticks - `code` or `command output`.
To format code or scripts in a separate block, use triple backticks.
Use a language prefix next to the top line of triple backticks, with no spaces, to highlight code - ```shell.
```Markdown
code block
```
code block
Unordered lists:
<br> (for example, to list links);Ordered (numbered) lists:
Due to the fact that the documentation is still under development and is regularly updated, we do not use numbered lists yet.
You can create an inline link by enclosing the link text in square brackets [ ] and the URL in parentheses ( ), without spaces.
[IX package manager](https://github.com/stal-ix/ix)
The link text is enclosed in square brackets, the link itself is enclosed in parentheses, without spaces.
[STALIX.md](/STALIX.html)
A relative link is a link that is relative to the current file. Define relative links to navigate to other files in the same repository, as absolute links may not work in clones of a repository.
To create a horizontal dividing line, use three (or more) hyphens ---. The horizontal line is used to separate special blocks of text (e.g. Exercise).
---
Exercise<br>
special text block
---
Exercise
special text block
In the text of the document, the block is separated by two dividing lines, at the top and bottom, if the block is at the end of the document (for example, comments) - by one dividing line at the top. There must be a blank line between the last line of the block text and the bottom dividing line.
To ignore Markdown formatting, use \ before a Markdown character.