Skip to content

Commit fbb8728

Browse files
fblettnerfblettner
committed
Add article for mkdocs and update readme
1 parent a3387a0 commit fbb8728

File tree

2 files changed

+498
-1
lines changed

2 files changed

+498
-1
lines changed

‎README.md

Lines changed: 244 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,244 @@
1-
# Documentation generated with mkdocs
1+
# Installing and Deploying MkDocs Material with GitHub Pages
2+
3+
This guide explains how to install and deploy MkDocs Material for creating beautiful documentation sites. It also includes steps to automate deployment to GitHub Pages.
4+
5+
### What's Included in the Site
6+
7+
The provided MkDocs Material configuration is designed to support a comprehensive documentation site with the following features:
8+
9+
- **Navigation**:
10+
* Multi-level navigation with tabs and collapsible sections.
11+
* Support for documentation, guides, blog posts, API references, and release notes.
12+
13+
- **Customization**:
14+
* Custom logo and favicon.
15+
* Light and dark themes with a toggle switch.
16+
* Customizable color palettes to match your branding.
17+
18+
- **Enhanced User Experience**:
19+
- Instant navigation with prefetching for fast transitions.
20+
- Sticky top navigation for ease of access.
21+
- Copy button for code snippets to improve developer productivity.
22+
23+
- **Plugins**:
24+
- `awesome-pages`: Automatically organizes navigation based on folder structure.
25+
- `minify`: Optimizes site assets for faster loading.
26+
- `blog`: Supports structured and visually appealing blog posts.
27+
- `search`: Integrated full-text search for quick access to content.
28+
29+
- **Content Types**:
30+
- Documentation sections for getting started, installation guides, and tutorials.
31+
- Blog posts with structured navigation and metadata.
32+
33+
- **Technical Enhancements**:
34+
- Cookie consent settings to comply with privacy policies.
35+
- CSP (Content Security Policy) meta tag for enhanced security.
36+
- Custom CSS and JavaScript to further tailor the site's appearance and functionality.
37+
38+
### Repository Features
39+
40+
The repository includes:
41+
42+
1. A complete `mkdocs.yml` configuration with navigation, theme, and plugin settings.
43+
2. A `docs/` directory with pre-structured files and folders for easy customization.
44+
3. Workflow configuration (`.github/workflows/deploy.yml`) to automate deployment to GitHub Pages.
45+
4. Sample blog posts, API documentation, and guides to demonstrate how to structure content.
46+
5. Custom assets for branding, including a logo and favicon.
47+
48+
By cloning this repository, you can start with a fully functional MkDocs Material site and focus on adding your content instead of setting up the structure.
49+
50+
## Step 1: Prerequisites
51+
52+
Before starting, ensure you have the following:
53+
- **Python 3.x** installed (verify with `python --version`).
54+
55+
- **pip** installed (verify with `pip --version`).
56+
57+
- A **GitHub repository** to host your documentation.
58+
59+
- Git configured locally with a GitHub personal access token if needed.
60+
61+
62+
## Step 2: Install MkDocs Material
63+
64+
1. **Create a Virtual Environment** (optional but recommended):
65+
```bash
66+
python -m venv venv
67+
source venv/bin/activate # On Windows, use venv\Scripts\activate
68+
```
69+
70+
2. **Install MkDocs Material**:
71+
```bash
72+
pip install mkdocs-material
73+
```
74+
75+
3. **Verify Installation**:
76+
```bash
77+
mkdocs --version
78+
```
79+
80+
---
81+
82+
## Step 3: Create the MkDocs Project
83+
84+
1. **Create a New MkDocs Project**:
85+
```bash
86+
mkdocs new my-project
87+
cd my-project
88+
```
89+
90+
2. **Edit the `mkdocs.yml` File**:
91+
Replace the default configuration with the following:
92+
93+
```yaml
94+
site_name: Your Site Name
95+
site_url: Your Site URL
96+
97+
theme:
98+
name: material
99+
logo: assets/your_logo.png
100+
favicon: assets/your_logo.png
101+
custom_dir: overrides
102+
palette:
103+
- media: "(prefers-color-scheme: light)"
104+
primary: blue grey
105+
accent: amber
106+
scheme: default
107+
toggle:
108+
icon: material/weather-night
109+
name: Switch to dark mode
110+
- media: "(prefers-color-scheme: dark)"
111+
primary: blue grey
112+
accent: amber
113+
scheme: slate
114+
toggle:
115+
icon: material/weather-sunny
116+
name: Switch to light mode
117+
features:
118+
- content.code.copy
119+
- navigation.instant
120+
- navigation.tabs
121+
- navigation.path
122+
- navigation.top
123+
- navigation.footer
124+
- header.autohide
125+
126+
# example of navigation
127+
nav:
128+
- Home: index.md
129+
- Liberty:
130+
- Getting Started: liberty/getting-started.md
131+
- Installation:
132+
- Architecture: liberty/technical/architecture.md
133+
- Docker Installation Guide: liberty/technical/installation.md
134+
- Installation Tools Deployment Guide: liberty/technical/tools-deployment.md
135+
- Liberty Deployment Guide: liberty/technical/liberty-deployment.md
136+
- Create Linux Services: liberty/technical/linux-services.md
137+
- Enable SSL with Traefik: liberty/technical/post-ssl.md
138+
- Blog:
139+
- blog/index.md
140+
141+
plugins:
142+
- search
143+
- awesome-pages
144+
- minify
145+
- blog
146+
147+
extra:
148+
social:
149+
- icon: fontawesome/brands/github
150+
link: your social link for github
151+
- icon: fontawesome/brands/linkedin
152+
link: your social link for linkedin
153+
meta:
154+
- name: Content-Security-Policy
155+
value: frame-ancestors 'self' https://giscus.app;
156+
consent:
157+
title: Cookie consent
158+
actions:
159+
- accept
160+
- manage
161+
- reject
162+
description: >-
163+
We use cookies to recognize your repeated visits and preferences,
164+
as well as to measure the effectiveness of our documentation.
165+
markdown_extensions:
166+
- attr_list
167+
- pymdownx.highlight:
168+
anchor_linenums: true
169+
linenums: true
170+
line_spans: __span
171+
pygments_lang_class: true
172+
- pymdownx.inlinehilite
173+
- pymdownx.snippets
174+
- pymdownx.superfences
175+
extra_css:
176+
- css/custom.css
177+
extra_javascript:
178+
- js/extra.js
179+
copyright: >
180+
Copyright © 2024 Nomana-IT –
181+
<a href="#__consent">Change cookie settings</a>
182+
```
183+
184+
3. **Add Your Documentation Files**:
185+
Organize your files under the `docs/` folder as per the navigation structure defined in the `mkdocs.yml`.
186+
187+
---
188+
189+
## Step 4: Deploy to GitHub Pages
190+
191+
1. **Set Up GitHub Actions**:
192+
Add the following configuration in `.github/workflows/deploy.yml`:
193+
194+
```yaml
195+
name: ci
196+
on:
197+
push:
198+
branches:
199+
- master
200+
- main
201+
permissions:
202+
contents: write
203+
jobs:
204+
deploy:
205+
runs-on: ubuntu-latest
206+
steps:
207+
- uses: actions/checkout@v4
208+
- name: Configure Git Credentials
209+
run: |
210+
git config user.name github-actions[bot]
211+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
212+
- uses: actions/setup-python@v5
213+
with:
214+
python-version: 3.x
215+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
216+
- uses: actions/cache@v4
217+
with:
218+
key: mkdocs-material-${{ env.cache_id }}
219+
path: .cache
220+
restore-keys: |
221+
mkdocs-material-
222+
- run: pip install mkdocs-material mkdocs-awesome-pages-plugin mkdocs-minify-plugin
223+
- run: mkdocs gh-deploy --force
224+
```
225+
226+
2. **Push Your Changes**:
227+
Commit and push your project to the `main` branch of your GitHub repository:
228+
```bash
229+
git add .
230+
git commit -m "Initial documentation setup"
231+
git push origin main
232+
```
233+
234+
3. **Access Your Site**:
235+
After GitHub Actions finish deploying, your site will be live at:
236+
```
237+
https://<your-github-username>.github.io/<repository-name>/
238+
```
239+
240+
---
241+
242+
## Conclusion
243+
244+
Your MkDocs Material documentation is now installed and deployed with GitHub Pages! This workflow ensures automated deployment and a professional look for your documentation site.

0 commit comments

Comments
 (0)