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 a search terms, 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:
Rich structured text:
User input
Use `item`
for user supplied input, or item in a list or tree::
Preview:
Select
Basemap
layer.
Markdown:
Rich structured text:
Use `text`
for user supplied text input:
Preview:
Use the Search field enter
Ocean*
.
Markdown:
Rich structured text:
Use ++key++
for keyboard keys.
Preview:
Press Ctrl+S to search.
Markdown:
Rich structured text:
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
- Remeber me
-
Unchecked
Press Login.
Markdown: definition lists
1. To login as the GeoServer administrator using the default password:
**User**
: `admin`
**Password**
: `geoserver`
**Remeber 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:
- :kbd:`admin`
* - Password:
- :kbd:`geoserver`
* - Remember me
- Unchecked
Press :guilabel:`Login`.
Applications, commands and tools
Use bold and italics for proper names of applications, commands, tools, and products.
Preview:
Launch pgAdmin and connect to the databsae tutorial
.
Markdown:
Rich structured text:
Files
Use bold monospace for files and folders:
Preview See configuration file WEB-INF/config-security/config-security-ldap.xml
for details
Markdown:
Rich structured text:
Links and references
Specific kinds of links:
Reference to other section of the document (some care is required to reference a specific heading):
Editors have option to manage records.
Editors have option to :ref:`manage <Publish records>` records.
Editors have option to [manage](../editor/publish/index.md#publish-records) records.
Download of sample files:
Example:
Download schema
example.xsd
.
Download schema :download:`example.xsd <files/example.xsd>`.
Download schema [**`example.xsd`**](files/example.xsd).
Icons, Images and Figures
Material for markdown has extensive icon support, for most user interface elements we can directly make use of the appropriate icon in Markdown:
Add cusotm icons to overrides/.icons/geocat
:
Figures are handled by convention, adding emphasized text after each image, and trust CSS rules to provide a consistent presentation:
Raw images are not used very often:
Tables
Documentation uses pipe-tables only (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
Here is a snippet to include markdown files inline, requires opening tag {%
and closing tag %}
:
Use a glob pattern to inline many files, shown with option to adjusting header level:
For including markdown files inline, we have to exclude them from mkdocs.yml
warnings:
Use include
to include normal files, shown with start and end to capture a snippet, and dedent for appearance:
Reference: