211 lines
4.9 KiB
Markdown
211 lines
4.9 KiB
Markdown
# Authoring Content with Markdown and MkDocs Material
|
|
|
|
This guide provides a brief overview of writing content using Markdown and leveraging the styling capabilities of the MkDocs Material theme for your Changemaker documentation site.
|
|
|
|
## Markdown Basics
|
|
|
|
Markdown is a lightweight markup language with plain-text formatting syntax. It's designed to be easy to read and write.
|
|
|
|
### Headings
|
|
```markdown
|
|
# Heading 1
|
|
## Heading 2
|
|
### Heading 3
|
|
```
|
|
|
|
### Emphasis
|
|
```markdown
|
|
*Italic text* or _Italic text_
|
|
**Bold text** or __Bold text__
|
|
~~Strikethrough text~~
|
|
```
|
|
|
|
### Lists
|
|
|
|
**Ordered List:**
|
|
```markdown
|
|
1. First item
|
|
2. Second item
|
|
3. Third item
|
|
```
|
|
|
|
**Unordered List:**
|
|
```markdown
|
|
- Item A
|
|
- Item B
|
|
- Sub-item B1
|
|
- Sub-item B2
|
|
* Item C
|
|
```
|
|
|
|
### Links
|
|
```markdown
|
|
[Link Text](https://www.example.com)
|
|
[Link with Title](https://www.example.com "An example link")
|
|
[Relative Link to another page](../apps/code-server.md)
|
|
```
|
|
|
|
### Images
|
|
```markdown
|
|
|
|
```
|
|
*Place your images in the `mkdocs/docs/assets/images/` directory (or create it if it doesn't exist) and reference them accordingly.*
|
|
|
|
### Code Blocks
|
|
|
|
**Inline Code:**
|
|
Use backticks: `this is inline code`.
|
|
|
|
**Fenced Code Blocks (Recommended for multi-line code):**
|
|
Specify the language for syntax highlighting.
|
|
|
|
````markdown
|
|
```python
|
|
def hello_world():
|
|
print("Hello, world!")
|
|
```
|
|
|
|
```html
|
|
<h1>Hello</h1>
|
|
```
|
|
````
|
|
|
|
### Blockquotes
|
|
```markdown
|
|
> This is a blockquote.
|
|
> It can span multiple lines.
|
|
```
|
|
|
|
### Horizontal Rule
|
|
```markdown
|
|
---
|
|
***
|
|
```
|
|
|
|
### Tables
|
|
```markdown
|
|
| Header 1 | Header 2 | Header 3 |
|
|
| :------- | :------: | -------: |
|
|
| Align L | Center | Align R |
|
|
| Cell 1 | Cell 2 | Cell 3 |
|
|
```
|
|
|
|
## MkDocs Material Theme Features
|
|
|
|
MkDocs Material provides many enhancements and custom syntax options on top of standard Markdown.
|
|
|
|
### Admonitions (Call-outs)
|
|
|
|
These are great for highlighting information.
|
|
|
|
```markdown
|
|
!!! note
|
|
This is a note.
|
|
|
|
!!! tip "Optional Title"
|
|
Here's a helpful tip!
|
|
|
|
!!! warning
|
|
Be careful with this action.
|
|
|
|
!!! danger "Critical Alert"
|
|
This is a critical warning.
|
|
|
|
!!! abstract "Summary"
|
|
This is an abstract or summary.
|
|
```
|
|
|
|
Supported types include: `note`, `abstract`, `info`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`.
|
|
|
|
### Code Blocks with Titles and Line Numbers
|
|
|
|
Your `mkdocs.yml` is configured for `pymdownx.highlight` which supports this.
|
|
|
|
````markdown
|
|
```python title="my_script.py" linenums="1"
|
|
print("Hello from Python")
|
|
```
|
|
````
|
|
|
|
### Emojis
|
|
|
|
Your `mkdocs.yml` has `pymdownx.emoji` enabled.
|
|
|
|
```markdown
|
|
:smile: :rocket: :warning:
|
|
```
|
|
See the [MkDocs Material Emoji List](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search-for-emojis) for available emojis.
|
|
|
|
### Footnotes
|
|
|
|
Your `mkdocs.yml` has `footnotes` enabled.
|
|
|
|
```markdown
|
|
This is some text with a footnote.[^1]
|
|
|
|
[^1]: This is the footnote definition.
|
|
```
|
|
|
|
### Content Tabs
|
|
|
|
Group related content under tabs.
|
|
|
|
````markdown
|
|
=== "Tab 1 Title"
|
|
Content for tab 1 (can be Markdown)
|
|
|
|
=== "Tab 2 Title"
|
|
Content for tab 2
|
|
|
|
```python
|
|
# Code blocks work here too
|
|
print("Hello from Tab 2")
|
|
```
|
|
````
|
|
|
|
### Task Lists
|
|
```markdown
|
|
- [x] Completed task
|
|
- [ ] Incomplete task
|
|
- [ ] Another task
|
|
```
|
|
|
|
### Styling with Attributes (`attr_list`)
|
|
|
|
You can add CSS classes or IDs to elements.
|
|
|
|
```markdown
|
|
This is a paragraph with a custom class.
|
|
{: .my-custom-class }
|
|
|
|
## A Heading with an ID {#custom-heading-id}
|
|
```
|
|
This is useful for applying custom CSS from your `extra.css` file.
|
|
|
|
### Buttons
|
|
|
|
MkDocs Material has a nice way to create buttons from links:
|
|
|
|
```markdown
|
|
[This is a button link](https://example.com){ .md-button }
|
|
[Primary button](https://example.com){ .md-button .md-button--primary }
|
|
[Another button](another-page.md){ .md-button }
|
|
```
|
|
|
|
## Editing Workflow
|
|
|
|
1. **Use Code Server**: Access Code Server from your Changemaker dashboard.
|
|
2. **Navigate**: Open the `mkdocs/docs/` directory.
|
|
3. **Create or Edit**: Create new `.md` files or edit existing ones.
|
|
4. **Save**: Save your changes (`Ctrl+S` or `Cmd+S`).
|
|
5. **Preview**:
|
|
* If you have `mkdocs serve` running (either locally on your machine if developing there, or in a terminal within Code Server pointing to the `mkdocs` directory), your documentation site (usually at `http://localhost:8000` or `http://127.0.0.1:8000`) will auto-reload.
|
|
* Alternatively, you can use VS Code extensions like "Markdown Preview Enhanced" within Code Server for a live preview pane.
|
|
|
|
## Further Reading
|
|
|
|
* [MkDocs Material Reference](https://squidfunk.github.io/mkdocs-material/reference/): The official documentation for all features.
|
|
* [Markdown Guide](https://www.markdownguide.org/basic-syntax/): For general Markdown syntax.
|
|
|
|
This guide should give you a solid start. Explore the MkDocs Material documentation for even more advanced features like diagrams, math formulas, and more complex page layouts.
|