Add style guidelines and syntax cheatsheet

* Add guidelines for alternative text
* Add guidelines for explicit targets for
cross references
* Add doc cheat sheet for MyST and Markdown

contribute/anbox-style-guide.md

@@ -33,6 +33,21 @@ Anbox Cloud documentation is written in a combination of MyST and Markdown synta
 * Avoid using multiple section titles sequentially without any text between them.
 * Avoid manual HTML anchors, links to section titles can be picked up from the page-level table of contents.
 
+## Cross references
+
+Always use [explicit targets](https://webaim.org/techniques/alttext/) for pages and sections to cross reference content within documentation. For external links or to reference a section on the same page, use markdown link syntax.
+
+The target names must be unique for each page and topic.
+
+Anbox Cloud documentation adheres to the following convention when naming explicit targets:
+* Reference: `ref-xxx-yyy`
+* Explanation: `exp-xxx-yyy`
+* How-to guides: `howto-xxx-yyy`
+* Tutorials: `tut-xxx-yyy`
+* Section targets in any topic: `sec-xxx-yyy`
+
+This helps in maintaining consistency in target naming and creating unique target names.
+
 ## Admonishments
 
 While admonishments can be useful to convey important information, they can be a distraction when used often. So before adding an admonishment, assess if the content really belongs in one.
@@ -77,6 +92,12 @@ While images and screenshots are very helpful in visual appeal and getting the m
 
 Simple images can be made using an image editor of your choice or you can use [diagrams.net](https://www.diagrams.net).
 
+### Alternative text for images
+
+Use alternative text (or alt text) for images when visual details cannot be included in the written content. You can leave the alternative text empty if it is more appropriate, for example, an icon that has a label.
+
+When writing alt text for images, consider the content, its context and purpose. It should accurately reflect the content and at the same time be concise.
+
 ## Redirects
 
-Add redirects whenever a file path changes as it affects the URL of the page.
+Set up redirects in [`custom_conf.py`](/custom_conf.py) whenever a file path changes as it affects the URL of the page.

contribute/doc-cheat-sheet.md

@@ -0,0 +1,227 @@
+---
+orphan: true
+---
+(cheat-sheet-myst)=
+# Markdown/MyST cheat sheet
+
+This file contains the syntax for commonly used Markdown and MyST markup. The best way to use it is to open it in your text editor and copy-paste the markup you need.
+
+See the [MyST style guide](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/) for detailed information and conventions. Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information on MyST.
+
+## H2 heading
+
+### H3 heading
+
+#### H4 heading
+
+##### H5 heading
+
+## Inline formatting
+
+- {guilabel}`UI element`
+- `code`
+- {command}`command`
+- *Italic*
+- **Bold**
+
+## Code blocks
+
+Start a code block:
+
+    code:
+      - example: true
+
+```
+# Demonstrate a code block
+code:
+  - example: true
+```
+
+```yaml
+# Demonstrate a code block
+code:
+  - example: true
+```
+
+## Links
+
+- [Canonical website](https://canonical.com/)
+- {ref}`a_section_target_myst`
+- {ref}`Link text <a_section_target_myst>`
+- {doc}`index`
+- {doc}`Link text <index>`
+
+## Navigation
+
+Use the following syntax::
+
+    ```{toctree}
+    :hidden:
+
+    sub-page1
+    sub-page2
+    ```
+
+## Lists
+
+1. Step 1
+   - Item 1
+      - Sub-item
+   - Item 2
+      1. Sub-step 1
+      1. Sub-step 2
+1. Step 2
+   1. Sub-step 1
+      - Item
+   1. Sub-step 2
+
+Term 1
+: Definition
+
+Term 2
+: Definition
+
+## Tables
+
+## Markdown tables
+
+| Header 1                           | Header 2 |
+|------------------------------------|----------|
+| Cell 1<br>Second paragraph         | Cell 2   |
+| Cell 3                             | Cell 4   |
+
+Centered:
+
+| Header 1                           | Header 2 |
+|:----------------------------------:|:--------:|
+| Cell 1<br>Second paragraph         | Cell 2   |
+| Cell 3                             | Cell 4   |
+
+## List tables
+
+```{list-table}
+   :header-rows: 1
+
+* - Header 1
+  - Header 2
+* - Cell 1
+
+    Second paragraph
+  - Cell 2
+* - Cell 3
+  - Cell 4
+```
+
+Centered:
+
+```{list-table}
+   :header-rows: 1
+   :align: center
+
+* - Header 1
+  - Header 2
+* - Cell 1
+
+    Second paragraph
+  - Cell 2
+* - Cell 3
+  - Cell 4
+```
+
+## Notes
+
+```{note}
+A note.
+```
+
+```{tip}
+A tip.
+```
+
+```{important}
+Important information
+```
+
+```{caution}
+This might damage your hardware!
+```
+
+## Images
+
+![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png)
+
+```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
+   :width: 100px
+   :alt: Alt text
+
+   Figure caption
+```
+
+## Tabs
+
+````{tabs}
+```{group-tab} Tab 1
+
+Content Tab 1
+```
+
+```{group-tab} Tab 2
+Content Tab 2
+```
+````
+
+## Glossary
+
+```{glossary}
+
+some term
+  Definition of the example term.
+```
+
+{term}`some term`
+
+## More useful markup
+
+- ```{versionadded} X.Y
+- {abbr}`API (Application Programming Interface)`
+
+----
+
+## Custom extensions
+
+Related links at the top of the page (surrounded by `---`):
+
+    relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)
+    discourse: 12345
+
+Terms that should not be checked by the spelling checker: {spellexception}`Incrrect`
+
+A single-line terminal view that separates input from output:
+
+```{terminal}
+   :input: command
+   :user: root
+   :host: vampyr
+   :dir: /home/user/directory/
+
+the output
+```
+
+A multi-line version of the same:
+
+```{terminal}
+   :user: root
+   :host: vampyr
+   :dir: /home/user/directory/
+
+:input: command 1
+output 1
+:input: command 2
+output 2
+```
+
+A link to a YouTube video:
+
+```{youtube} https://www.youtube.com/watch?v=drOCjcDpnng
+   :title: Demo
+```