Update markdown features doc

docs/doc-markdown.md

@@ -3,6 +3,43 @@ id: doc-markdown
 title: Markdown Features
 ---
 
+## Markdown Headers
+
+### Documents
+
+Documents use the following markdown header fields that are enclosed by a line `---` on either side:
+
+`id`: A unique document id. If this field is not present, the document's `id` will default to it's file name (without the extension).
+
+`title`: The title of your document. If this field is not present, the document's `title` will default to it's `id`.
+
+`sidebar_label`: The text shown in the document sidebar for this document. If this field is not present, the document's `sidebar_label` will default to it's `title`.
+
+For example:
+
+```markdown
+---
+id: doc1
+title: My Document
+sidebar_label: Document
+---
+```
+
+Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id.
+
+For example:
+
+```markdown
+---
+id: version-1.0.0-doc1
+title: My Document
+sidebar_label: Document
+original_id: doc1
+---
+```
+
+## Extra Features
+
 Docusaurus supports some extra features when writing documentation in markdown.
 
 ### Linking other Documents
@@ -10,13 +47,23 @@ Docusaurus supports some extra features when writing documentation in markdown.
 You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.
 
 Example:
+```markdown
+[This links to another document](other-document.md)
 ```
-[This links to another document](/docs/en/other-document.md)
-```
-If the permalink in the header of `other-document.md` is `/docs/en/other-document.html`, this markdown will automatically get converted into a link to `/docs/en/other-document.html` once it gets rendered.
+This markdown will automatically get converted into a link to `/docs/other-document.html` (or the appropriately translated/versioned link) once it gets rendered.
 
 This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.
 
+### Linking to Images and Other Assets
+
+Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into `docs/assets` and `website/blog/assets`, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.
+
+Example:
+```markdown
+![alt-text](assets/doc-image.png)
+```
+
+
 ### Generating Table of Contents
 
 You can make an autogenerated list of links, which can be useful as a table of contents for API docs.
@@ -24,7 +71,7 @@ You can make an autogenerated list of links, which can be useful as a table of c
 In your markdown file, insert a line with the text <`AUTOGENERATED_TABLE_OF_CONTENTS>`. Write your documentation using `h3` headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <`AUTOGENERATED_TABLE_OF_CONTENTS>`.
 
 Example:
-```
+```markdown
 ### `docusaurus.function(a, b)`
 
 Text describing my function
@@ -37,7 +84,7 @@ Text describing my function
 
 will lead to a table of contents of the functions:
 
-```
+```markdown
 - `docusaurus.function(a, b)`
 - `docdoc(file)`
 ```