Skip to content

Commit a54e975

Browse files
codecompass-1codecompass-1
authored
Initial commit
0 parents  commit a54e975

File tree

11 files changed

+362
-0
lines changed

11 files changed

+362
-0
lines changed

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
github: shadil-rayyan

‎.github/workflows/ci.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: ci
2+
on:
3+
push:
4+
branches:
5+
- master
6+
- main
7+
permissions:
8+
contents: write
9+
jobs:
10+
deploy:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- name: Configure Git Credentials
15+
run: |
16+
git config user.name github-actions[bot]
17+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: 3.x
21+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
22+
- uses: actions/cache@v4
23+
with:
24+
key: mkdocs-material-${{ env.cache_id }}
25+
path: ~/.cache
26+
restore-keys: |
27+
mkdocs-material-
28+
- run: pip install -r requirements.txt
29+
- run: mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# MkDocs
2+
site/
3+
4+
# Python
5+
__pycache__/
6+
*.py[cod]
7+
*$py.class
8+
venv/
9+
.venv/
10+
env/
11+
.env/
12+
build/
13+
dist/
14+
*.egg-info/
15+
16+
# OS
17+
.DS_Store
18+
Thumbs.db

‎README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# MkDocs Material Template
2+
3+
A high-performance, feature-rich template for MkDocs using the Material theme.
4+
5+
## ✨ Features
6+
7+
- **Standard Plugins**: `minify`, `search`, `git-revision-date-localized`, `git-authors`, `tags`.
8+
- **Advanced Markdown**: Admonitions, Tabs, Mermaid diagrams, Math (Latex), Footnotes, Tasklists, Emojis, and more.
9+
- **Premium UX**: Instant loading, sticky navigation, "Back to Top" button, social links, and code copy button.
10+
- **CI/CD Ready**: GitHub Actions workflow included for automatic deployment to GitHub Pages.
11+
- **Reproducible**: `requirements.txt` included for easy setup.
12+
13+
## 🚀 Quick Start
14+
15+
1. **Clone/Use this template**.
16+
2. **Install dependencies**:
17+
```bash
18+
pip install -r requirements.txt
19+
```
20+
3. **Start the dev server**:
21+
```bash
22+
mkdocs serve
23+
```
24+
4. **Edit `mkdocs.yml`**: Update the `site_name`, `repo_url`, and other metadata.
25+
26+
## 🌐 Deployment
27+
28+
This template is set up to deploy automatically via GitHub Actions.
29+
30+
1. **Push to `main`**: Any push to the `main` branch triggers the deployment workflow.
31+
2. **Configure GitHub Pages**:
32+
- Go to your repository **Settings** > **Pages**.
33+
- Under **Build and deployment** > **Source**, select **"Deploy from a branch"**.
34+
- Select the **`gh-pages`** branch (created after the first successful action run) and the **`/(root)`** folder.
35+
- Click **Save**.
36+
37+
## 📁 Structure
38+
39+
- `docs/`: Markdown files and documentation source.
40+
- `mkdocs.yml`: Configuration file.
41+
- `.github/workflows/ci.yml`: GitHub Actions for automated deployment.
42+
- `requirements.txt`: Python dependencies.
43+
- `.gitignore`: Standard git exclusions.
44+
45+
## 📄 License
46+
47+
This template is open-source and free to use.

‎docs/assets/favicon.ico‎

15 KB
Binary file not shown.

‎docs/assets/logo.png‎

56.3 KB
Loading

‎docs/index.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# ✨ Modern MkDocs Template
2+
3+
Welcome to your new documentation site! This template is pre-configured with the best plugins and extensions for a professional experience.
4+
5+
---
6+
7+
## 🚀 Key Features
8+
9+
- 🌓 **Dark Mode** support is built-in and follows system preferences by default.
10+
- 📱 **Mobile Friendly** design that looks great on any screen.
11+
- 🔍 **Instant Search** with highlighting and suggestions.
12+
- 📊 **Mermaid Diagrams** for flowcharts, sequences, and more.
13+
- 🔡 **Latex Math** support via Arithmatex.
14+
15+
---
16+
17+
## 📝 Markdown Examples
18+
19+
### 💡 Admonitions
20+
21+
!!! tip "Pro Tip"
22+
Use admonitions to highlight important information. They come in various flavors like `note`, `abstract`, `info`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, and `example`.
23+
24+
### 📑 Content Tabs
25+
26+
=== "Python"
27+
```python
28+
def welcome():
29+
print("Welcome to MkDocs Material!")
30+
```
31+
32+
=== "JavaScript"
33+
```javascript
34+
function welcome() {
35+
console.log("Welcome to MkDocs Material!");
36+
}
37+
```
38+
39+
### 📉 Diagrams
40+
41+
```mermaid
42+
graph LR
43+
A[Plan] --> B[Write]
44+
B --> C[Deploy]
45+
C --> D{Happy?}
46+
D -- Yes --> A
47+
D -- No --> B
48+
```
49+
50+
### 🔢 Math Equations
51+
52+
When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) and they are
53+
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$
54+
55+
### ✅ Task Lists
56+
57+
- [x] Create project
58+
- [x] Configure extensions
59+
- [ ] Write documentation
60+
- [ ] Profit!
61+
62+
### 🎨 Icons & Emojis
63+
64+
- :material-rocket-launch: Built for speed
65+
- :fontawesome-brands-github: Open source
66+
- :octicons-device-camera-video-24: Media friendly
67+
- :smile: :fire: :heart:
68+
69+
---
70+
71+
## 🛠️ Getting Started
72+
73+
1. **Install dependencies**:
74+
```bash
75+
pip install -r requirements.txt
76+
```
77+
78+
2. **Run locally**:
79+
```bash
80+
mkdocs serve
81+
```
82+
83+
3. **Build site**:
84+
```bash
85+
mkdocs build
86+
```

‎docs/setup.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Setup Guide
2+
3+
This page explains how to get started with this template.
4+
5+
## Prerequisites
6+
7+
- Python 3.8 or higher
8+
- Git
9+
10+
## Installation
11+
12+
```bash
13+
pip install -r requirements.txt
14+
```
15+
16+
## Configuration
17+
18+
Edit `mkdocs.yml` to customize your site:
19+
20+
```yaml
21+
site_name: My Awesome Project
22+
```
23+
24+
## Deployment
25+
26+
Simply push to `main` or `master` branch to trigger the GitHub Action.

‎mkdocs.yml‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
site_name: mkdocs_template
2+
site_description: A modern documentation template built with MkDocs Material.
3+
site_author: SHADIL A M
4+
site_url: https://shadil-rayyan.github.io/mkdocs_template/
5+
6+
# Repository
7+
repo_name: mkdocs_template
8+
repo_url: https://github.com/shadil-rayyan/mkdocs_template
9+
edit_uri: edit/main/docs/
10+
11+
theme:
12+
name: material
13+
custom_dir: overrides
14+
logo: assets/logo.png
15+
favicon: assets/favicon.ico
16+
17+
features:
18+
- navigation.instant
19+
- navigation.instant.prefetch
20+
- navigation.instant.progress
21+
- navigation.tracking
22+
- navigation.tabs
23+
- navigation.tabs.sticky
24+
- navigation.sections
25+
- navigation.expand
26+
- navigation.path
27+
- navigation.top
28+
- navigation.footer
29+
- navigation.indexes
30+
- search.highlight
31+
- search.suggest
32+
- search.share
33+
- content.code.copy
34+
- content.code.annotate
35+
- content.tabs.link
36+
- toc.follow
37+
38+
font:
39+
text: Inter
40+
code: JetBrains Mono
41+
42+
palette:
43+
- media: "(prefers-color-scheme)"
44+
toggle:
45+
icon: material/brightness-auto
46+
name: Switch to system preference
47+
- media: "(prefers-color-scheme: light)"
48+
scheme: default
49+
primary: indigo
50+
accent: indigo
51+
toggle:
52+
icon: material/brightness-7
53+
name: Switch to light mode
54+
- media: "(prefers-color-scheme: dark)"
55+
scheme: slate
56+
primary: indigo
57+
accent: indigo
58+
toggle:
59+
icon: material/brightness-4
60+
name: Switch to dark mode
61+
62+
plugins:
63+
- search
64+
- minify:
65+
minify_html: true
66+
- git-revision-date-localized:
67+
enable_if_directory_urls: true
68+
type: datetime
69+
- git-authors:
70+
show_email: false
71+
- tags
72+
73+
extra:
74+
social:
75+
- icon: fontawesome/brands/github
76+
link: https://github.com/shadil-rayyan
77+
- icon: fontawesome/brands/twitter
78+
link: https://twitter.com/shadilrayyan
79+
- icon: fontawesome/brands/linkedin
80+
link: https://linkedin.com/in/shadilam
81+
82+
consent:
83+
title: Cookie consent
84+
description: >-
85+
We use cookies to recognize your repeated visits and preferences, as well
86+
as to measure the effectiveness of our documentation.
87+
88+
analytics:
89+
provider: google
90+
property: G-XXXXXXXXXX
91+
92+
feedback:
93+
title: Was this page helpful?
94+
ratings:
95+
- icon: material/emoticon-happy-outline
96+
name: This page was helpful
97+
data: 1
98+
note: Thanks for your feedback!
99+
- icon: material/emoticon-sad-outline
100+
name: This page could be improved
101+
data: 0
102+
note: >-
103+
Thanks for your feedback! Help us improve this page using our
104+
<a href="..." target="_blank" rel="noopener">feedback form</a>.
105+
106+
markdown_extensions:
107+
- abbr
108+
- admonition
109+
- attr_list
110+
- def_list
111+
- footnotes
112+
- md_in_html
113+
- toc:
114+
permalink: true
115+
- tables
116+
- pymdownx.arithmatex:
117+
generic: true
118+
- pymdownx.betterem:
119+
smart_enable: all
120+
- pymdownx.caret
121+
- pymdownx.critic
122+
- pymdownx.details
123+
- pymdownx.emoji:
124+
emoji_index: !!python/name:material.extensions.emoji.twemoji
125+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
126+
- pymdownx.highlight:
127+
anchor_linenums: true
128+
line_spans: __span
129+
pygments_lang_class: true
130+
- pymdownx.inlinehilite
131+
- pymdownx.keys
132+
- pymdownx.magiclink:
133+
- pymdownx.mark
134+
- pymdownx.smartsymbols
135+
- pymdownx.snippets:
136+
check_paths: true
137+
- pymdownx.superfences:
138+
custom_fences:
139+
- name: mermaid
140+
class: mermaid
141+
format: !!python/name:pymdownx.superfences.fence_code_format
142+
- pymdownx.tabbed:
143+
alternate_style: true
144+
- pymdownx.tasklist:
145+
custom_checkbox: true
146+
- pymdownx.tilde

‎overrides/.gitkeep‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Keep this directory tracked by git even if empty.

0 commit comments

Comments
 (0)