# 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
![Alt text for image](/assets/images/changemaker.png "Optional Image Title")
```
*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.