MkDocs¶
Episode 01
Episode 01¶
example === "Windows" ### What we need * Terminal * Visual Studio Code * Obsidian * GitHub account ### Making plane web with MkDocs
1. Make folder for web
2. Left click folder to OPEN IN TERMINAL
*in Terminal*
3. Check **pip** version
```bash
python --version
```
1. if Python ‘was not found’ Paste
```bash
python
```
4. Paste
```bash
python -m venv venv
```
5. Paste
```bash
.\venv\Scripts\activate
```
6. Check pip version
```bash
pip --version
```
1. if pip ‘was not found’ Paste
```bash
pip install pip
```
7. Install MkDocs
```bash
pip install mkdocs-material
```
8. Paste
```bash
venv\Scripts\activate
```
9. Create a new site
```bash
mkdocs new .
```
10. Open code in VS
```bash
code .
```
11. Serve MkDocs web
```bash
mkdocs serve
```
12. Hold **Ctrl** and click on link to see your website
!!! warning
after closing **Terminal** it will stop serving web on your device.
### Open/serve web
*in Terminal*
1. Find web folder
```
cd Desktop\mkdocs
```
2. Paste
```
.\venv\Scripts\activate.bat
```
3. Open code in VS
```
code .
```
4. Serve MkDocs web
```
mkdocs serve
```
### Link MkDocs
*Visual Studio Code*
```yaml title="mkdocs.yml" hl_lines="2-4"
site_name: My MkDocs Material Documentation
site_url: https://sitename.example
theme:
name: material
```
### Customization
1. Change color pallete
1. Primary colors
```yaml title="mkdocs.yml" hl_lines="5"
site_name: My MkDocs Material Documentation
site_url: https://sitename.example
theme:
name: material
primary: orange
```
2. Accent colors
```yaml title="mkdocs.yml" hl_lines="6"
site_name: My MkDocs Material Documentation
site_url: https://sitename.example
theme:
name: material
primary: orange
accent: purple
```
2. Dark and Light mode
```yaml title="mkdocs.yml" hl_lines="4 5 6 7 8 9 10 12 13 14 15 16 17 18"
theme:
name: material
palette:
- scheme: default
primary: deep orange
accent: purple
toggle:
icon: material/brightness-7
name: Switch to dark mode
- scheme: slate
primary: purple
accent: deep orange
toggle:
icon: material/brightness-4
name: Switch to light mode
```
### Adding basic content
*Obsidian*
1. Headlines
```yaml title="index.md"
# headline 01
## headline 02
### headline 03
#### headline 04
##### headline 05
###### headline 06
```
!!! example "result"
# headline 01
## headline 02
### headline 03
#### headline 04
##### headline 05
###### headline 06
2. Paragraph
```yaml title="index.md"
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
```
!!! example "result"
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
3. Emphasis
```yaml title="index.md"
**BOLD**
*italic*
<ins>underline</ins>
<s>strikethrough</s>
```
!!! example "result"
**BOLD**
*italic*
<ins>underline</ins>
<s>strikethrough</s>
4. Links
```yaml title="index.md"
very cool [link here](https://www.youtube.com/watch?v=HP5xhyPn58U&ab_channel=hr-Sinfonieorchester%E2%80%93FrankfurtRadioSymphony)
```
!!! example "result"
very cool [link here](https://www.youtube.com/watch?v=HP5xhyPn58U&ab_channel=hr-Sinfonieorchester%E2%80%93FrankfurtRadioSymphony)
6. Images/Gifs
1. make new folder for Images
```hl_lines="2"
├─ .obsidian/
├─ assets/
├─ docs/
├─ venv/
└─ mkdocs.yml
```
2. upload images into folder
```hl_lines="3"
├─ .obsidian/
├─ assets/
│ └─ img01.jpg
├─ docs/
├─ venv/
└─ mkdocs.yml
```
3. in **Obsidian**
```yaml title="index.md"
{ width=300px }
```
{ width=300px }
### Upload on GitHub
1. make new folder for ci.yml in webfolder
```
├─ .obsidian/
├─ assets/
├─ .github/ workflows
│ └─ ci.yml
├─ docs/
├─ venv/
└─ mkdocs.yml
```
2. paste code to ci.yml
```yaml title="ci.yml"
name: ci
on:
push:
branches:
- master
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- uses: actions/setup-python@v5
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- uses: actions/cache@v4
with:
key: mkdocs-material-${{ env.cache_id }}
path: .cache
restore-keys: |
mkdocs-material-
- run: pip install mkdocs-material mkdocs-awesome-pages-plugin
- run: mkdocs gh-deploy --force
```
3. In [GitHub](https://github.com/) create new repository. Set to **Public**.
=== "Linux"
=== "IOS"
Episode 02
Episode 03
Episode 04