https://github.com/tameronline/indexmd
📚 Auto-generate professional documentation from your README.md using MkDocs + CLI panel.
https://github.com/tameronline/indexmd
cli documentation github-pages markdown mkdocs
Last synced: 4 months ago
JSON representation
📚 Auto-generate professional documentation from your README.md using MkDocs + CLI panel.
- Host: GitHub
- URL: https://github.com/tameronline/indexmd
- Owner: TamerOnLine
- License: mit
- Created: 2025-06-20T04:48:18.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-20T10:30:45.000Z (about 1 year ago)
- Last Synced: 2025-10-21T14:50:24.750Z (8 months ago)
- Topics: cli, documentation, github-pages, markdown, mkdocs
- Language: Python
- Homepage: https://tameronline.github.io/indexMD/
- Size: 25 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 📦 indexMD – Markdown-Based Documentation Generator
A lightweight documentation generator powered by MkDocs and custom scripts to automate README-based documentation deployment.
---
[](LICENSE)
[](https://github.com/TamerOnLine/indexMD/wiki/01.-Home)
[](./docs/)
[](https://github.com/TamerOnLine/indexMD/stargazers)
[](https://github.com/TamerOnLine/indexMD/fork)
[](https://github.com/TamerOnLine/indexMD/issues)
[](https://github.com/TamerOnLine/indexMD/pulls)
[](https://www.python.org/downloads/release/python-3120/)
[](https://www.mkdocs.org/)
[](https://pypi.org/project/pip/)
[](https://github.com/TamerOnLine/indexMD/actions)
[](https://github.com/TamerOnLine/indexMD)
[](https://github.com/TamerOnLine/indexMD/commits)
[](https://github.com/TamerOnLine/indexMD/graphs/contributors)
[](https://github.com/TamerOnLine)
---
📘 [Live Documentation](https://tameronline.github.io/indexMD/)
---
## 📖 Full Documentation – Wiki
Need step-by-step guides on installation, usage, customization, or contributions?
Explore the **official project Wiki** for complete technical documentation:
➡️ [View the Wiki](https://github.com/TamerOnLine/indexMD/wiki/01.-Home)
> 👤 📝 Maintained and regularly updated for all user levels: beginners, contributors, and advanced users.
---
---
## Table of Contents
- [Features ✨](#features)
- [Clone the Repository 📥](#clone-the-repository)
- [Quick Start 🚀](#quick-start)
- [Optional: Upgrade pip (recommended) ⬆️](#optional-upgrade-pip-recommended)
- [Install Dependencies 📦](#install-dependencies)
- [indexMD Control Panel 🎛️](#indexmd-control-panel)
- [CLI Options Explained 🧩](#cli-options-explained)
- [Project Structure 🧱](#project-structure)
---
## Features
- 📄 **Markdown-based documentation**
- 📦 **MkDocs for static site generation**
- 📑 **Custom HTML overrides**
- 🌐 **Customizable themes and styles**
- 📖 **Multi-section support** (About, Contact, Privacy, Terms…)
- 🔗 **Important links section**
[🔝 Back to Top](#table-of-contents)
---
## Clone the Repository
To get started, clone this repository to your local machine using Git:
```bash
git clone https://github.com/TamerOnline/indexMD.git
cd indexMD
```
- Make sure you have Git installed: [https://git-scm.com](https://git-scm.com)
📽️ Quick Clone of the indexMD repository in action
[🔝 Back to Top](#table-of-contents)
---
## Quick Start
### Create Virtual Environment
```bash
# Windows
py -3.12 -m venv venv
.\venv\Scripts\Activate
```
📽️ Quick setup of indexMD on Windows in action
[🔝 Back to Top](#table-of-contents)
---
```bash
# macOS / Linux
python3 -m venv venv
source venv/bin/activate
```
---
### Optional: Upgrade pip (recommended)
Before installing dependencies, it's recommended to upgrade `pip` to the latest version to avoid compatibility issues.
```bash
python -m pip install --upgrade pip
```
📽️ Upgrading pip on Windows (recommended)
[🔝 Back to Top](#table-of-contents)
---
### Install Dependencies
```bash
pip install -r requirements.txt
```
📽️ Quick install of the index MD Tools in action
[🔝 Back to Top](#table-of-contents)
---
## indexMD Control Panel
```bash
py cli.py
```
🧠 A simple yet powerful command-line interface to manage your documentation workflow easily:
Build, Prepare, Serve, Deploy, or just Check version — all in one menu!
### CLI Options Explained
| Option | Description |
|--------|-------------|
| `1. Build Documentation` | Generates the static site using `mkdocs build`. |
| `2. Prepare README` | Converts the `README.md` into `index.md` for homepage. |
| `3. Serve Locally` | Launches a local dev server using `mkdocs serve`. |
| `4. Deploy` | Deploys the site to GitHub Pages using `mkdocs gh-deploy`. |
| `5. Check Version` | Displays current versions of key tools like MkDocs. |
| `6. Exit` | Exits the CLI interface. |
[🔝 Back to Top](#table-of-contents)
---
## Project Structure
The following is the structure of the main project directory:
```text
./
├── 📁 docs/
│ ├── 📁 sections/
│ │ ├── about.md
│ │ ├── contact.md
│ │ ├── important-links.md
│ │ ├── privacy.md
│ │ └── terms.md
│ ├── 📁 stylesheets/
│ │ └── extra.css
│ └── index.md
├── 📁 overrides/
│ └── 📁 partials/
│ ├── footer.html
│ └── header.html
├── .gitignore
├── LICENSE
├── README.md
├── build_all.py
├── cli.py
├── mkdocs.yml
├── prepare_docs.py
└── requirements.txt
```
[🔝 Back to Top](#table-of-contents)
---
## 📦 Install via pip (coming soon)
This project will soon be available on PyPI for easy installation.
Once published, you will be able to install it using:
```bash
pip install indexmd