contributing: Update style guide for Markdown doc (#5219)

Removes mentions of specifics of HTML syntax, replaces them by simpler Markdown instructions which reflect the current practice used in Markdown files in the code.
OSGeo · Feb 27, 2025 · ba980b5 · ba980b5
1 parent d8afe68
commit ba980b5
Showing 1 changed file with 46 additions and 60 deletions.
diff --git a/doc/development/style_guide.md b/doc/development/style_guide.md
@@ -236,95 +236,88 @@ Documentation of a tool should come with clear descriptions, hints on the
 implemented algorithm and example(s) with figures.
 
 Each tool (also called "module") comes with its own manual page written in
-simple HTML. The HTML file contains **no header nor footer**. The complete HTML
-file is autogenerated during the compilation process (with ``--html-description
-parameter``). In order to make sure that manuals build without issues, it can be
-useful to validate the HTML before submitting, e.g. with
-[validator.w3.org](https://validator.w3.org/).
+Markdown. The Markdown file contains **no header nor footer**. The complete
+file is autogenerated during the compilation process (with ``--md-description
+parameter``). In order to make sure that manuals build without issues, we run
+a Markdown linter on all pull requests.
 
-Name the documentation file `'<tool>.html'`, e.g., if the tool is named
-r.example, the documentation file should be named `r.example.html`.
+Name the documentation file `'<tool>.md'`, e.g., if the tool is named
+r.example, the documentation file should be named `r.example.md`.
 
 ##### Markup style guide
 
 The structure consists of several required and optional sections:
 
-```html
-<h2>DESCRIPTION</h2>
+```markdown
+## DESCRIPTION
 <!-- required -->
 
-<h2>NOTES</h2>
+## NOTES
 <!-- suggested -->
 
-<h2>EXAMPLES</h2>
+## EXAMPLES
 <!-- suggested -->
 
-<h2>TODO</h2>
+## TODO
 <!-- optional -->
 
-<h2>KNOWN ISSUES</h2>
+## KNOWN ISSUES
 <!-- optional -->
 
-<h2>REFERENCES</h2>
+## REFERENCES
 <!-- optional -->
 
-<h2>SEE ALSO</h2>
+## SEE ALSO
 <!-- required -->
 
-<h2>AUTHORS</h2>
+## AUTHORS
 <!-- required -->
 ```
 
 Sections _Notes_, _Examples_, _References_, and _Authors_ can be also in
 singular form (e.g, _Note_).
 
-Note that HTML is converted to man pages by
-[utils/g.html2man/](../../utils/g.html2man/).
-Since the man conversion is limited, please use no other HTML tags than:
-
-```html
-<a> <b> <body> <br> <code> <dd> <dl> <dt> <em>
-<h2> <h3> <h4> <head> <hr> <i> <img> <li> <ol> <p>
-<pre> <sup> <table> <td> <th> <title> <tr> <ul>
-```
+Note that Markdown is converted to html using [MkDocs](https://www.mkdocs.org/).
+See also [supported Markdown elements by MkDocs](https://www.markdownguide.org/tools/mkdocs/)
+and CI-enforced [linter rules](https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md).
 
 More notes on markup:
 
-- Tool names (i.e., v.category) should be emphasized with `<em>v.category</em>`.
-- Flags and parameter names written in boldface like `<b>-f</b>` and
-  `<b>input</b>`.
-- Shell commands, names, values, etc. should use `<tt>42</tt>`.
-- Emphasized phrases `<i>should use italics</i>`.
+- Tool names (i.e., v.category) should be emphasized like `*v.category*`.
+- Flags and parameter names written in boldface like `**-f**` and
+  `**input**`.
+- Shell commands, names, values, etc. should use `` `42` ``.
+- Emphasized phrases `*should use italics*`.
 - In order to minimize potential git merge conflicts, please break a line at
   approximately 70-80 chars.
+- A line break in the resulting HTML is created by adding two spaces at the end
+  of a line. Use this sparingly and only when necessary.
 
 Examples should be coded like this:
 
-```html
-<div class="code">
-<pre>
+````markdown
+```sh
 v.to.db map=soils type=area option=area column=area_size unit=h
-</pre>
-</div>
 ```
 
-The `<h2>SEE ALSO</h2>` section of each page should be alphabetized:
+```python
+gs.run_command("g.region", flags="p")
+```
+````
+
+The `SEE ALSO` section of each page should be alphabetized:
 
-```html
-<em>
-  <a href="d.shade.html">d.shade</a>, <a href="r.shade.html">r.shade</a>
-</em>
+```markdown
+*[d.shade](d.shade.md), [r.shade](r.shade.md)*
 ```
 
 Alternatively, the section can provide details on how each of the linked tools
 or pages is relevant:
 
-```html
-<em>
-  <a href="r.shade.html">r.shade</a> for computing shaded relief,
-  <a href="d.shade.html">d.shade</a> for displaying shaded relief with other data,
-  <a href="g.region.html">g.region</a> for managing the resolution.
-</em>
+```markdown
+*[r.shade](r.shade.md) for computing shaded relief,  
+[d.shade](d.shade.md) for displaying shaded relief with other data,  
+[g.region](g.region.md) for managing the resolution.*
 ```
 
 In this case, the list can be ordered thematically rather than alphabetically.
@@ -352,7 +345,7 @@ mogrify -resize 600x file.png
 Smaller images are also possible when appropriate, e.g. when a lot of images are
 included or they are something special, e.g. equations, icons or simple
 diagrams. Larger images are supported, too, see below for an optimal inclusion
-into the HTML page.
+into the Markdown page.
 
 Please **compress** PNG images with:
 
@@ -380,21 +373,14 @@ with a width of 600 pixel but it is clickable in the manual page). If a larger
 image is displayed as shrunk, both **width** and **height** HTML parameters
 (values must be calculated according to the picture size!) should be set:
 
-```html
-<div align="center" style="margin: 10px">
-  <a href="r_viewshed.png">
-    <img
-      src="r_viewshed.png"
-      width="600"
-      height="600"
-      alt="r.viewshed example"
-      border="0"
-    /></a><br/>
-  <i>Figure: Viewshed shown on shaded terrain (observer position in the
-    north-east quadrant with white dot; 5m above ground)</i>
-</div>
+```markdown
+![r.viewshed example](r_viewshed.png)  
+*Figure: Viewshed shown on shaded terrain (observer position in the
+north-east quadrant with white dot; 5m above ground)*
 ```
 
+_Note the 2 spaces after the image._
+
 ## Best Practices
 
 ### General