Markdown standards

this page will explain how to format your content to fit the standard used by this website ir engine documentation uses a very restricted set of github markdown for formatting its content multitude of otherwise perfectly legal markdown rules are strictly forbidden by this standard please make sure to pay extra attention to these rules if you are already accustomed to markdown syntax the markdown problem markdown is a really powerful and easy to use alternative to html it has a very intuitive and easy to understand syntax that can also give format to text in a similar level to how html can one of its key features is how flexible it is but, at the same time, this flexibility is also its biggest problem maintaining a cohesive format across a team with different users/writers that all have their own unique quirks and style for writing markdown, and all contribute to a project of the size of ir engine's documentation (this website) , is extremely challenging without having a single and unified standard the solution compressing the wide range of styling and formatting options that markdown offers, down into a very minimal and simplified ruleset, pretty much solves the problem altogether as such, this standard aims to be as minimal, simple and intuitive to use as possible markdown itself is very simple, but this standard simplifies it even further every syntax rule will allow for only one single and unified way of using it this ruleset aims to achieve a clean and cohesive codebase that won't look internally messy, and/or have to be refactored to fit the website's quality standard every time a different contributor pushes new content into the site it might feel very limiting and restricting if you already have developed your own workflow or quirks on how to write markdown syntax but please remember how important it is to have a cohesive ruleset when working on a project of the size of this website rules this website uses a very restricted and minimal subset of github markdown ( gfm https //github github com/gfm/ ) writing markdown with the standard explaned in this article will feel a lot stricter than usual because of this, every rule will have a tab listing the (otherwise legal) syntax alternatives that gfm permits but we don't use < syntax "gotcha" every < character must be escaped (like \\< ) reason docusaurus interprets md files as mdx https //mdxjs com/docs/what is mdx this means that all instances of \<something> will be interpreted as a jsx/tsx component not respecting this rule will make docusaurus completely fail at compiling the website this is the most likely cause of ci errors when pushing your content for the first time notes and highlights use admonitions for giving side notes, tips and/or warning the user about things that could cause problems for them here is the complete list of admonition types https //docusaurus io/docs/markdown features/admonitions and how to use them this note contains side information that is useful for the user, but shouldn't distract them from the main body of content this block contains information of high importance that the user should pay attention to this block contains information that the user could be informed about, as it might make their life easier when followed this block contains information that the user should be warned about, as it might create problems for them this block contains information that the user must be warned about, as it will create problems for them when ignored custom admonitions admonitions can have custom titles and even links https //www etheralengine com remember that admonitions can have custom titles that accept markdown syntax as usual don't overuse this feature, but remember that it can be very helpful depending on the situation ```md note[admonitions can have custom titles and even [links](https //www etheralengine com)] remember that admonitions can have custom titles that accept markdown syntax as usual don't overuse this feature, but remember that it can be very helpful depending on the situation ``` note > ```note ``` this note contains side information that is useful for the user, but that shouldn't distract them from the main body of the content note this note contains side information that is useful for the user, but that shouldn't distract them from the main body of the content important > ```important ``` this block contains information of high importance that the user should pay attention to important this block contains information of high importance that the user should pay attention to tip > ```tip ``` this block contains information that the user could be informed about, as it might make their life easier when followed tip this block contains information that the user could be informed about, as it might make their life easier when followed warning > ```warning ``` this block contains information that the user should be warned about, as it might create problems for them warning this block contains information that the user should be warned about, as it might create problems for them danger > ```danger ``` this block contains information that the user must be warned about, as it will create problems for them when ignored danger this block contains information that the user must be warned about, as it will create problems for them when ignored titles usage of # pages must start their first title with # title , not ## title or ### title reasoning markdown `#` becomes html ` ` the `#` title will be used for page title sidebar label the `sitemap xml` file for use by website crawlers this is critical for seo please make sure to use short titles that explain the content well ```md # title1 ## title2 ### title3 #### title4 ##### title5 ###### title6 ``` title1 \====== title2 \ our configuration stops listing sub sections in its table of contents sidebar at \<h5> title content separation align the first line of a section right up next to its title separating sections with two empty lines between them is preferrable reasoning having the first line of content of a section separate from their title is perfectly legal markdown to and turns into readable html but it makes the page a bit less clean and readable in markdown format # title1 each section's first line must be close to its title second line of this section \## title2 this line is also close to its title we also separated the sections with two empty lines, which is not mandatory but useful # title1 this section's first line has a space separating the line from its title second line of this section \## title2 this line is also not close to its title too many line separations make the page less readable in markdown format explicit heading ids titles can have a heading id https //docusaurus io/docs/next/markdown features/toc#heading ids different than its default use them only when you know the id will be linked to in multiple other places and its default id is prone to typing errors (eg the title contains strange characters, its name is misleading, etc) the id is an important reference that could be memorized the id is temporary and will change (not might change) the id is very long, and cannot be shorter / more concise `### very long title name {#short id}` this title will have its direct link as `url/path/to/page#short id``### very long title name` this title will be linked by default as `url/path/to/page#very long title name` paragraph separation end lines with double space for newline breaks within the same paragraph reasoning paragraphs and sentences get bunched together into very unreable blocks of text when not using ` ` at the end of lines note end of line ` ` converts into html ` ` this is a line ending with ` ` this second line will be aligned to the bottom of the previous one this is a line in another paragraph, separated from the other lines by leaving an empty line in between this is a line that does not end with this second line will be appended to the previous one, without any \<br> line breaks between them this line is separate from the other lines it is not affected by the rule all of these words are written in separate lines this is a clear and simple sentence this is another sentence that is also clear and simple this third sentence is also clear, simple, and should also be a separate line this fourth sentence already becomes really hard to conceptually separate from the others, just because line breaks were not used by this sentence, if the concepts were important to remember, you are already struggling to pay attention to this block of text and remember each individual concept, even if each sentence was clear, simple and easy to read individually all of the sentences in this block of code were written in separate lines without using at the end of each all of these words are written in separate lines this is a clear and simple sentence this is another sentence that is also clear and simple this third sentence is also clear, simple, and should also be a separate line this fourth sentence already becomes really hard to conceptually separate from the others, just because line breaks were not used by this sentence, if the concepts were important to remember, you are already struggling to pay attention to this block of text and remember each individual concept, even if each sentence was clear, simple and easy to read individually all of the sentences in this block of code were written in separate lines without using ` ` at the end of each text formatting asterisk ` ` for bold text underscore ` ` for italic text tilde ` ` for strikethrough text double ` ` underscore for bold text is not allowed single ` ` asterisk for italic text is not allowed single ` ` is not used for anything single ` ` tilde for strikethrough text is not allowed some markdown styles allow it, others dont double ` ` is the most commonly used version ```md double ` ` underscore for bold text is not allowed single ` ` asterisk for italic text is not allowed single ` ` is not used for anything single ` ` tilde for strikethrough text is not allowed ``` reasoning for clarity and simplicity, these caracters are reserved exclusively for one single purpose character ` ` reserved for bold text, even if it could be used for italic text character ` ` reserved for italic text, even if it could be used for bold text double ` ` is the most commonly used syntax for strikethrough text some markdown styles allow it, others dont bullet points bullet points must use ` ` numbered bullet points must use `n ` bullet point titles formatted as ` title some text` multi line bullet points are allowed (an preferred for clarity when they make sense) they must be aligned to the character above to work like this example this is a bullet point created with ` ` 1) this is a numbered bullet point created with `1)` this is a titled bullet point, that has the ` ` inside bold ```md this is a bullet point created with ` ` 1) this is a numbered bullet point created with `1)` this is a titled bullet point, that has the ` ` inside bold ``` reasoning double ` ` is reserved for bolds, and single ` ` is disallowed for simplicity numbered bullet points get converted into `n ` when rendered as ` ` in html makes more sense to already format them that way with markdown syntax bold titles formatted with ` ` outside bold is a small adjustment with apparently little gain its goal is to make titles a bit cleaner and more readable in both markdown and rendered html code blocks {#codeblock} code blocks must always define a language, even if that language is just ```text code blocks for programming languages must always add the showlinenumbers directive on their title code blocks should define a title="/path/to/file ext" if possible ```ts title="/path/to/somecodefile ts" showlinenumbers // this codeblock defines a title, so it gets a label // it defines the `showlinenumbers` directive, so its lines are numbered // it also gets syntax highlighting because it was marked with ```ts / @description this is a documentation comment @note jsdoc/tsdoc tags are also syntax hightlighted / function somefunction(arg1 \ type1 , arg2 \ type2 ) \ void { const one \ string = 'this is a thing' return; } \</tabitem> \<tabitem value="incorrect codeblock" label="valid but not allowed"> // this codeblock does not define a title, so it doesn't get a label // it does not define the showlinenumbers directive, so lines are not numbered // it also gets no highlighting because it didn't define a language / @description this is a documentation comment @note jsdoc/tsdoc tags are also syntax hightlighted / function somefunction(arg1 \ type1 , arg2 \ type2 ) \ void { const one \ string = 'this is a thing' return; } \</tabitem> \</tabs> \<details> \<summary>reasoning \</summary> \<div> single and simple rule always add a language to any block of code \ syntax highlighting makes code a lot easier to read \ giving a language, even when its just `text`, makes the writing workflow more consistent across the entire codebase giving a title and adding line numbers to codeblocks makes their presentation look a lot better and easier to understand and/or reference \</div> \</details> \<br>\</br> \### code inline \ inline code should be avoided as much as possible a proper syntax highlighed codeblock should be used instead only use inline code for highlighting text with a monospaced font \ inline code syntax must use single \\` characters example \\`this is code\\` turns into `this is code` \ triple \\`\\`\\` inline syntax is not allowed \<details> \<summary>reasoning \</summary> \<div> \ proper \\`\\`\\`bash codeblocks, as those mentioned in the \[previous section]\(#codeblock), are much more readable and clear \ the syntax \\`\\`\\`some bash command\\`\\`\\` is unnecessarily complex for achieving the exact same result as single \\` characters does \ triple \\`\\`\\` syntax is strictly reserved for codeblocks \</div> \</details> \<br>\</br> \### #todo lists \<tabs> \<tabitem value="todo html" label="rendered"> \ \[ ] task 1 \ \[x] task 1 1 \ \[ ] task 1 2 \ \[ ] task 2 \</tabitem> \<tabitem value="todo md" label="markdown"> ```md \ \[ ] task 1 \ \[x] task 1 1 \ \[ ] task 1 2 \ \[ ] task 2 reasoning the character ` ` is also used for bullet point, which conflicts with this rule but there is no alternative syntax to create todo tasklists with markdown