Markdown

These markdown conventions are carefully constructed for consistent representation of user interface elements, files, data and field input.

Markdown	Directive
strong	gui label, menu selection
`monospace`	text input, item selection
emphasis	figure (caption)
*strong-emphasis*	application, command
`monospace-strong`	file

Note

The above conventions are important for consistency and are required by the translation process.

As an example we do not wish to translate keyboard input, so these are represented as monospace text input.

User interface components

Use **strong** to name user interface components for interaction (press for buttons, click for link).

Preview:

Navigate to Data → Layers page, and press Add to create a new layer.

Markdown uses **strong**:

Navigate to **Data > Layers** page,
and press **Add** to create a new layer.

Rich structured text uses menuselection and guilabel directives:

Navigate to **Data --> Layers** page,
and press **Add** to create a new layer.

Selected input

Use item for user selected input, or item in a list or tree:

Preview:

Select Basemap layer.

Markdown uses monospace:

Select `Basemap` layer.

Rich structured text uses monospace:

Select ``Basemap`` layer.

Input text

Use monospace for user supplied text input:

Preview:

Use the Search field to enter: Ocean*

Markdown uses monospace:

Use the **Search** field enter: `Ocean*`

Rich structured text uses kbd directive:

Use the **Search** field to enter: ``Ocean*``

Keypress

Use key directive for keyboard keys.

Preview:

Press Control-s to search.

Markdown uses mkdocs-material keys formatting:

Press ++control+s++ to search.

Rich structured text:

Press `Control-s` to search.

Form input

Use definition list to document data entry. The field names use strong as they name a user interface element. Field values to input uses monspace as user input to type in.

Preview:

To login as the GeoServer administrator using the default password:

User:

admin

Password:

geoserver

Remember me

Unchecked

Press Login.

Markdown: definition lists

1.  To login as the GeoServer administrator using the default password:

    **User**

    :   `admin`


    **Password**

    :   `geoserver`


    **Remember me**

    :   Unchecked

    Press **Login**.

Rich structured text: list-table

#. To login as the GeoServer administrator using the default password:

   .. list-table::
      :widths: 30 70
      :width: 100%
      :stub-columns: 1

      * - User:
        - `admin`
      * - Password:
        - `geoserver`
      * - Remember me
        - Unchecked

   Press **Login**.

Applications, commands and tools

Use bold with italics for proper names of applications, commands, tools, and products.

Preview:

Launch pgAdmin and connect to the tutorial database.

Markdown:

Launch ***pgAdmin*** and connect to the `tutorial` database.

Rich structured text uses command directive:

Launch ***pgAdmin*** and connect to the ``tutorial`` database.

Files

Use bold with monospace for files and folders:

Preview

See configuration file WEB-INF/config-security/config-security-ldap.xml for details

Markdown:

See configuration file
**`WEB-INF/config-security/config-security-ldap.xml`**
for details

Rich structured text:

See configuration
file **`WEB-INF/config-security/config-security-ldap.xml`**
for details

Links and references

Internal References

Reference to other section of the document (some care is required to reference a specific heading):

Authors have access to translation for initial draft.

Markdown use of relative links and anchor:

Authors have access to [translation](../translate/language#translate) for initial draft.

reStructuredText use of ref directive:

Authors have access to `translation <../translate/language.rst#translate>`_ for initial draft.

Download of sample file

Sample file included in the documentation:

Download schema example.txt.

Markdown relative link, with text following bold with monospace file convention above:

Download text [**`example.txt`**](files/example.txt).

You may also experiment with mkdocs attr_list to supply a filename:

Download text [**`example.txt`**](files/example.txt) {:download="example.txt"} .

reStructured text uses downlaod directive:

Download text `example.txt <files/example.txt>`__.

Download of external file

To include sample file from outside of the documentation tree:

Open-source LICENSE.md

Note

This functionality is not supported by Material for mkdocs (or any plugin I could find). It is accomplished using the download.py hook described in setup.

To use download.py hook, create a download folder to hold staged files

Markdown refers to this folder using a relative link (like normal):

Open-source [**`LICENSE.md`**](download/LICENSE.md)

Create download/download.txt with list of files to stage during mkdocs build process:

# files list for mkdocs hook staging download content

LICENSE.md=../../../../LICENSE.md

reStructuredText uses download directive with relative path (you may starting leading / to indicate the root of the documentation source folder):

Open-source `LICENSE.md <download/LICENSE.md>`__

Icons, Images and Figures

Icons

Material for mkDocs has extensive icon support, for many user interface elements we can directly make use of the appropriate icon in Markdown:

1.  Press the *Validate :fontawesome-solid-check:* button at the top of the page.

Custom icons

Custom icons:

Empower everyone with open source geospatial

Material for MkDocs provides support for custom icons:

:osgeo-logo: Empower everyone with open source geospatial

Add images to overrides/.icons/ (yes it is a hidden folder):

overrides/
- .icons/
  - osgeo/
    logo.svg

reStructuredText does not offer custom icons, the closest is the use of substitutions to "inline" and image.

.. |osgeo_mark| image:: img/osgeo_mark.svg
   :width: 20
   :height: 20

|osgeo_mark| Empower everyone with open source geospatial

Warning

The mkdocs_translate and pandoc combo is unable to convert inline images at this time.

[WARNING] Reference not found for 'Key "osgeo_mark"' at build/migrate/guide/markdown.tmp.prep.rst_chunk line 5 column 13

Figures

Figures are used frequently to allow a caption to describe screen shots and diagrams.

Free and Open Source Software for Geospatial

Markdown handles figures are handled by convention adding emphasized text after each image.

![FOSS4G](img/foss4g.svg)
*Free and Open Source Software for Geospatial*

Note

The convention above depends on CSS rules in overrides/assets/stylesheets/extra.css to provide a consistent presentation:

img + em, .browser-border + em, .browser-mockup + em {
  display: block;
  text-align: left;
  font-size: 0.7rem;
  font-style: normal;
}

Note

The official Material for MkDocs answer for images with captions is to use md_in_html extension:

<figure markdown="span">
  ![FOSS4G](img/foss4g.svg){ scale="25%" }
  <figcaption>Free and Open Source Software for Geospatial</figcaption>
</figure>

reStructuredText has a figure directive:

.. code-block:: raw_markdown

   ![](img/foss4g.svg)
   *Free and Open Source Software for Geospatial*

Images

Image content:

Markdown provides inline image syntax.

![](img/foss4g.svg)

Use of mkdocs att_list can be used to adjust scale:

![](img/foss4g.svg){ scale="25%" }

reStructuredText has an image directive:

.. image:: img/foss4g.svg
   :scale: 25%

Tables

Material for MkDocs :squidfunkdata tables <reference/data-tables/> use pipe-tables approach (supported by both mkdocs and pandoc):

Leading | tailing |:

| First Header | Second Header | Third Header |
|--------------|---------------|--------------|
| Content Cell | Content Cell  | Content Cell |
| Content Cell | Content Cell  | Content Cell |

Column alignment using :

| First Header | Second Header | Third Header |
|:-------------|:-------------:|-------------:|
| Left         |    Center     |        Right |
| Left         |    Center     |        Right |

Inline content

Use of mkdocs-include-plugin provides ability to inline content. Example project uses following mkdocs.yml setup:

plugins:
  - include-markdown:
      preserve_includer_indent: true
      dedent: true
      comments: false

The official Material for mkdocs guidance is to use snippets however this did not offer the ability to include code examples and configuration from outside the document tree.

Reference

include content

Inlining a snippet from another file is helpful for material such as disclaimers or statements which are repeated in text.

Empower everyone with open source geospatial

Here is a snippet to include markdown files inline, requires opening tag {% and closing tag %}:

{/
  include-markdown 'files/vision_statement.txt'
/}

Note

Placeholders {/ and /} used to indicate location of {% and %} in above code example.

Writers can use include-markdown with a glob pattern to inline many files, and an option to adjusting header level. Together these two features can be used break up longer pages into more manageable size.

This takes the place of the sphinx-build include directive:

.. include:: files/vision_statement.txt

Note

You may wish to use the txt extension for included content. If you wish to use md extension you can adjust mkdocs.yml exclude or not not_in_nav to address warnings.

plugins:
  - exclude:
      glob:
        - '**/files/*.md'

include config and code

Including configuration and code examples:

<CharacterString>da165110-88fd-11da-a88f-000d939bc5d8</CharacterString>

Use include to include normal files, with optional use of start and end markers to capture a snippet, and dedent for appearance.

In this case we are including content into an xml code block to provide syntax highlighting, requires opening tag {% and closing tag %} within the code block:

``` xml
{/
     include 'files/record.xml'
     dedent="true"
     start="<!--start-->"
     end="<!--end-->"
/}
```

Note

Placeholders {/ and /} used to indicate location of {% and %} in above code example.

This takes the place of the sphinx-build literal-include directive:

.. literalinclude:: files/record.xml
   :language: xml
   :start-after: <!--start-->
   :end-before: <!--end-->
   :dedent: