You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This repo is archived. You can view files and clone it, but cannot push or open issues/pull-requests.

README.md 10KB

6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253
  1. # aldocs: alwaysdata documentation
  2. This documentation is generated using the [Hugo][1] static site generator.
  3. If you want to run the documentation project locally, take a look at the [main repository project][2].
  4. ## Working on documentation
  5. ### Update the content
  6. Pages of documentation are located in the `content` directory. The [folder tree](#files-organization) represent the navigation structure. Pages are written in markdown, with a YAML or a TOML Front Matter for metadata.
  7. ### Adding new pages
  8. When adding new pages, please take care of the [folder tree](#files-organization) to stay consistent with the overall documents architecture.
  9. ### i18n
  10. Please keep in mind that:
  11. 1. Default language is English (EN)
  12. 2. The Documentation is available both in English (EN) and French (FR)
  13. 3. If you do *not* precise the locale, then the page is considered to be in English
  14. You should create *both* version when creating a new content:
  15. ```sh
  16. $ hugo new path/to/page.en.md
  17. $ hugo new path/to/page.fr.md
  18. ```
  19. ⚠ Pay attention: all localized versions of a given page **must** have the same filename and must be in the same folder. You **only** have to update the extension to use the correct ISO locale (e.g. here above the extension `.en.md` becomes `.fr.md` for the french version).
  20. If you write a page that is _not_ in english, you should add a `url` entry in the front headers to fill the localized page url.
  21. ## Redacting content
  22. ### Types of pages
  23. When you create new pages, you should pass a [type][7] to start your page with a proper template, dedicated to the content you want to add.
  24. ```sh
  25. $ hugo new --kind man new/section/_index.en.md
  26. $ hugo new --kind man new/section/_index.fr.md
  27. ```
  28. Available types are:
  29. - `readme`: they only serve as introduction to a new section and should be used for `_index.[ln].md` files only
  30. - `howto`: step by step guide to explain a given action/task
  31. - `man`: concept page that explain ideas, concepts, and point to more details how-tos; they can be used for `_index.[ln].md` pages
  32. - `faq`: QnA sections related to a given domain; they should not appear in menu
  33. ### Files organization
  34. Files in the `content` folder are organized in [branches and leaf bundles][8]. Here's how you may keep your contents organized to stay consistent:
  35. ```
  36. content
  37. ├── guides <-- A section
  38. │ ├── _index.en.md <-- Section main page (aka chapter), en_US
  39. │ └── _index.fr.md <-- Section main page, fr_FR
  40. ├── marketplace
  41. │ ├── admin-panel_1click_app.en.jpg <-- Screenshot usable in the chapter, en_US
  42. | ├── admin-panel_1click_app.fr.jpg <-- Same screenshot, fr_FR version
  43. | ├── build-application-script <-- A page (leaf) bundle
  44. | | ├── images <-- Page images assets
  45. │ │ │ ├── create-script.en.png <-- Screenshot used in the page, en_US
  46. | | | └── create-script.fr.png <-- Same screenshot, fr_FR version
  47. │ │ ├── index.en.md <-- Page bundle content, en_US
  48. | | └── index.fr.md <-- Page bundle content, fr_FR
  49. │ ├── install-an-application.en.md <-- A Page leaf unbundled, en_US
  50. | ├── install-an-application.fr.md <-- Same Page leaf, fr_FR version
  51. │ ├── _index.en.md <-- Section chapter page, en_US
  52. | └── _index.fr.md <-- Section chpater page, fr_FR
  53. ├── _index.en.md <-- Documentation Homepage, en_US
  54. └── _index.fr.md <-- Documentation Homepage, fr_FR
  55. ```
  56. - Each _Section_ should have a _chapter_ page in the form of an `_index.[ln].md` page.
  57. - Pages (leafs) can be standalone (with a dedicated name), or bundled (in a named folder, and named `index.[ln].md`). You can bundle all pages if you want, but unless you need to add _assets_ to the page, you can shortname them and avoid the leaf folder.
  58. - If you need to add assets to a page, you **must** bundle them, and place images in a `images` folder into the bundle.
  59. - If you need to add assets to a section page (aka chapter), you **must** put them at the same level as the branch page.
  60. ### Files naming
  61. Here's the conventions about files naming you have to follow:
  62. - All filenames are **lowercase**
  63. - Avoid whitespaces in the filenames, replace them with `-`
  64. - If you need to namespace your files (like, for images), use `_` as a separator for namespaces (e.g. `admin-panel_add-domain`)
  65. - Chapter pages are named `_index`
  66. - Bundle pages are named `index`
  67. - Leaf pages can be named as you wish until you follow above rules
  68. - All filenames use a locale suffix, regardless of their type (e.g. `my-page.en.md` or `my-image.fr.png`)
  69. - Localized versions of a given page **must** have the **same** filename, with only the locale suffix changed
  70. ### Available shortcodes
  71. You can extend the commonmark (markdown) syntax by using shortcodes that will render custom HTML in your page.
  72. #### Images: `fig`
  73. To add page/bundle images into your pages, use the `fig` shortcode:
  74. ```
  75. {{< fig "[url]" ("[desc]") >}}
  76. ```
  77. The `url` parameter in mandatory and refer to the image path relatively to the markdown document. I.e. to include an image in the `images` folder of the page bundle, use the following syntax:
  78. ```
  79. {{< fig "images/my-image.en.png" >}}
  80. ```
  81. The second parameter contains a caption for the image an is optional.
  82. The shortcode will render a `<figure>` HTML tag.
  83. #### Permalinks: `ref`
  84. To link to another page of the documentation, use the `ref` shortcode:
  85. ```
  86. {{< ref "pagename" >}}
  87. ```
  88. I.e. to link the _Install an application_ page in the _Marketplace_ section, use:
  89. ```
  90. [Install an application]({{< ref "marketplace/install-an-application" >}})
  91. ```
  92. The `pagename` parameter may be a folder (internally resolved as it index file) or a file, with or without extension, or locale suffix. The locale is detected automatically from the current page one.
  93. #### Notices: `notice [type]`
  94. If you need to embed some insert to highlight aside contents in your page (like a _warning_ or a _tip_ aside content), you can rely on the `notice` shortcode:
  95. ```
  96. {{% notice warning %}}
  97. Pay attention to this insert!
  98. {{% /notice %}}
  99. ```
  100. You've got four types available:
  101. - `warning`: _red_, for pay attention content
  102. - `info`: _orange_, useful to excerpt some alternative option
  103. - `note`: _blue_, for some extra but optional content
  104. - `tip`: _green_, for useful tips
  105. ### Tables
  106. Tables are formatted using the [Github Flavored][9] syntax:
  107. ```
  108. | Header 1 | Header 2 | Header 3 |
  109. |:--------------|--------------|--------------:|
  110. | left aligned | auto aligned | right aligned |
  111. | 2nd line | regular cell | regular cell |
  112. | 3rd line | regular cell | regular cell |
  113. ```
  114. - Inner cells **must** be surrounded with one space
  115. - Rows starts and end with a pipe `|`
  116. - Headers separator **may** indicate the column alignment with the colon `:` marker
  117. - Cells **must** be padded to ensure a consistent alignment with monospaced fonts (see example above)
  118. ### Footnotes
  119. You can rely on the [PHP Markdown Extra Footnotes syntax][10] to dynamically generate footnotes:
  120. ```md
  121. Hello World[^1]
  122. [^1]: this is an associated footnote
  123. ```
  124. Please note that the separator line and the anchor links are auto-generated.
  125. ### Conventions
  126. Here's some conventions we use to write our documentation. Please stick to them.
  127. 1. Variables in code samples should appear surrounded by brackets: `mysql -u [username]`
  128. 2. Avoid the `~` character to indicated the home dir and prefer the `$HOME` version, more understandable
  129. 3. Avoid the use of the `![]()` markdown syntax for internal images, prefer the `fig` shortcode
  130. 4. Restrain from using quotes `>` as they're often not relevant in technical documentation, esêcially if you want to highlight some content, prefer the `notice` shortcode
  131. 5. Codeblocks should use the backtick notation <code>```</code> optionally followed by the syntax marker (e.g. <code>python</code>)
  132. 6. Variables and inline command/code **must** be surrounded by backticks
  133. 7. Emphasis is done by using one underscore surrounding; strong by using double stars sourrounding
  134. 8. Avoid the use of HTML tags and markup in your content, Markdown is enough (i.e. no `<br>` nor `<font>` tags)
  135. 9. We use the following names for replacement:
  136. - `foo`: for a lambda name, username, etc
  137. - `bar`: for a second one
  138. - `example.org`, `example.net`, `example.com`: for lambda domains
  139. ### Front Matter
  140. Pages **must** start with a Front Matter block,. it may be written in YAML (using a `---` surrounding block marker) or in TOML (`+++` block marker):
  141. ```
  142. +++
  143. url = "/fr/applithèque/créer-son-script-d-application/"
  144. title = "Créer son propre script d'application"
  145. menuTitle = "Créer son propre script"
  146. layout = "man"
  147. weight = 5
  148. hidden = true
  149. +++
  150. ```
  151. The following fields are mandatory:
  152. - `title`: the page title
  153. - `layout`: the type of page. Possible values are `man`, `howto`, `faq`. Exception exists for chapter pages where you can avoid the `layout` field, and replace it with a `chapter = true` one
  154. You can add more metadata to your pages in the Front Matter:
  155. - `menuTitle`: the page title in the navigation menu, default is the `title` value
  156. - `weight`: an index to sort entries in the navigation menu
  157. - `hidden`: does the page should appear in the navigation menu?
  158. - `url`: for non *en_US* (default language) pages, you should explicitely fill the `url` field to localize it. Do _not_ forget the locale prefix (e.g. `/fr/`), and always add a final `/` at the end.
  159. Please keep in mind to entirely remove the `draft` field when your page is ready to be published rather than putting it to `false`.
  160. ### Tags
  161. To add new tag(s) to a page, add a tags entry in the front headers:
  162. ```md
  163. +++
  164. title = "My Page"
  165. tags = ["tag 1", "tag 2"]
  166. +++
  167. Content
  168. ```
  169. You can add as many tag as you wish, but we should limit to 3 tags per page. Tags can be written with `<spaces>` in their name.
  170. ***
  171. More documentation is available on [Hugo doc][6].
  172. [1]: https://gohugo.io
  173. [2]: https://git.madslab.net/alwaysdata/aldocs
  174. [6]: https://gohugo.io/documentation/
  175. [8]: https://gohugo.io/content-management/page-bundles/
  176. [9]: https://github.github.com/gfm/#tables-extension-