Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
documentation
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Iterations
Wiki
Requirements
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Locked files
Build
Pipelines
Jobs
Pipeline schedules
Test cases
Artifacts
Deploy
Releases
Package registry
Container registry
Harbor Registry
Model registry
Operate
Environments
Terraform modules
Monitor
Incidents
Service Desk
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Code review analytics
Issue analytics
Insights
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
This is an archived project. Repository and other project resources are read-only.
Show more breadcrumbs
e-INFRA.cz
documentation
Commits
ad3f9e50
Commit
ad3f9e50
authored
2 years ago
by
Jan Siwiec
Browse files
Options
Downloads
Patches
Plain Diff
Mkdocs 101
parent
78e90ec2
No related branches found
No related tags found
1 merge request
!21
Mkdocs 101
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
topics/about-us/docs/contribute/style-guide/mkdocs-101.md
+115
-0
115 additions, 0 deletions
topics/about-us/docs/contribute/style-guide/mkdocs-101.md
topics/about-us/mkdocs.yml
+1
-0
1 addition, 0 deletions
topics/about-us/mkdocs.yml
with
116 additions
and
0 deletions
topics/about-us/docs/contribute/style-guide/mkdocs-101.md
0 → 100644
+
115
−
0
View file @
ad3f9e50
# MkDocs 101
This section describes the essentials of markup language allowing you to write a simple page.
Only the most basic elements are described here to give you a general idea of the workflow.
For more information, see
[
mkdocs-material
][
a
]
.
## Headers
```
# Header 1
## Header 2
Up to #### Header 4
```
## Text
Formatting:
```
*italics*
**bold**
```
One
`enter`
acts as space, blank line breaks the text into paragraph.
## Lists
Indentation: 4 spaces
Bullets point symbols
`*`
or
`–`
for unordered list.
Ordered list start with number, can be the same number, MkDocs will translate it, e.g.:
```
1. entry1
1. entry2
1. entry3
```
Will automatically translate to
```
1. entry1
2. entry2
3. entry3
```
## Tables
```
| First Header | Second Header | Third Header |
| ------------ | ------------- | ------------ |
| Content Cell | Content Cell | Content Cell |
| Content Cell | Content Cell | Content Cell |
```
Aligning columns to left/center/right is done by placing
`:`
characters at the beginning and/or end of the divider:
```
| Left align | Center align | Right align |
| :----------- | :------------: | -----------: |
| Content | Content | Content |
```
## Code blocks
Starts and ends with three backticks
`\``
.
You can specify the environment/language (console in the example below) at the beginning. But not necessary.
\`
``console
Some code
In code block
\```
Word marked with single
`\``
from both sides creates
`code formatting`
inline.
## Admonitions
Start with
`!!!`
. Text is indented with 4 spaces. Can add title of the admonition using
`“`
, for example:
!!! Note “Alternative text”
This is a note admonition.
Most often we use
`Note`
,
`Tip`
,
`Important`
, and
`Warning`
admonitions. (But less is more.)
## Links
Writing simply www.address.com translates as plaintext in MkDocs. So a reference is required.
For links, we use reference ID, for example:
`[www.address.com][a]`
or
`[see this section][1]`
And then put the reference link at the end of the file:
```
[a]: www.address.com
[1]: https://docs.it4i.cz/dice/
```
We usually use alphabet for links outside the docs and numerals for links inside the docs.
Links inside the docs can be relative.
## Images
We don’t use reference ID for images. So for example:
```

```
can be added in the text to show the respective image at that place.
Empty
`[]`
means there is no alternative text for the image.
[
a
]:
https://squidfunk.github.io/mkdocs-material/reference/
This diff is collapsed.
Click to expand it.
topics/about-us/mkdocs.yml
+
1
−
0
View file @
ad3f9e50
...
...
@@ -10,5 +10,6 @@ nav:
-
Style Guide
:
-
Writing practices
:
./contribute/style-guide/writing-practices.md
-
Style guide
:
./contribute/style-guide/style.md
-
MkDocs 101
:
./contribute/style-guide/mkdocs-101.md
-
List of rules
:
./contribute/style-guide/test-rules.md
-
Technical Details
:
./contribute/technical-details.md
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment