https://github.com/elijahr/mkdocstrings-nim
MkDocs API documentation generator for Nim projects
https://github.com/elijahr/mkdocstrings-nim
documentation-generator mkdocs mkdocs-material mkdocstrings nim
Last synced: 4 months ago
JSON representation
MkDocs API documentation generator for Nim projects
- Host: GitHub
- URL: https://github.com/elijahr/mkdocstrings-nim
- Owner: elijahr
- License: mit
- Created: 2025-11-30T22:25:34.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-21T10:25:15.000Z (5 months ago)
- Last Synced: 2025-12-23T02:43:39.264Z (5 months ago)
- Topics: documentation-generator, mkdocs, mkdocs-material, mkdocstrings, nim
- Language: Jinja
- Homepage:
- Size: 1.12 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# mkdocstrings-nim
[](https://pypi.org/project/mkdocstrings-nim/)
[](https://pypi.org/project/mkdocstrings-nim/)
[](https://github.com/elijahr/mkdocstrings-nim/blob/main/LICENSE)
[](https://elijahr.github.io/mkdocstrings-nim/)
Generate API documentation for your Nim projects.
mkdocstrings-nim extracts documentation from Nim source files using the Nim compiler's AST, including module docstrings, procedure signatures, parameter types, return types, and pragma annotations. It renders the documentation as HTML using [MkDocs](https://www.mkdocs.org/) and [mkdocstrings](https://mkdocstrings.github.io/).
**[Full Documentation](https://elijahr.github.io/mkdocstrings-nim/)** | **[Changelog](https://github.com/elijahr/mkdocstrings-nim/blob/main/CHANGELOG.md)**
## Quick Start
This guide gets you from zero to a running documentation server for your Nim project.
### Prerequisites
- **Nim** compiler installed and in PATH ([install Nim](https://nim-lang.org/install.html))
- **Python 3.9+** ([install Python](https://www.python.org/downloads/))
### 1. Install the tools
```bash
pip install mkdocs mkdocs-material mkdocstrings-nim
```
### 2. Create mkdocs.yml
In your Nim project root, create `mkdocs.yml`:
```yaml
site_name: My Nim Project
theme:
name: material
plugins:
- search
- mkdocstrings:
handlers:
nim:
paths: [src] # Where your .nim files are
options:
show_source: true
docstring_style: rst
```
### 3. Create your docs
Create a `docs/` directory with an `index.md`:
```bash
mkdir docs
```
**docs/index.md:**
```markdown
# My Nim Project
Welcome to my project documentation.
## API Reference
::: mymodule
```
The `::: mymodule` directive tells mkdocstrings to extract and render documentation from `src/mymodule.nim`.
### 4. Run the docs server
```bash
mkdocs serve
```
Open http://127.0.0.1:8000 to see your documentation.
### 5. Build for deployment
```bash
mkdocs build
```
This creates a `site/` directory with static HTML ready to deploy to GitHub Pages, Netlify, or any static host.
## Writing Nim Docstrings
Use `##` comments to document your Nim code:
```nim
## This module provides greeting utilities.
proc greet*(name: string): string =
## Greet someone by name.
##
## :param name: The name to greet
## :returns: A greeting message
result = "Hello, " & name & "!"
type
Config* = object
## Configuration for the greeter.
prefix*: string ## The greeting prefix
suffix*: string ## The greeting suffix
```
Supported docstring styles: `rst` (default), `google`, `numpy`, `epydoc`.
## Configuration Options
Configure in `mkdocs.yml` under `plugins > mkdocstrings > handlers > nim > options`:
| Option | Default | Description |
|--------|---------|-------------|
| `paths` | `["src"]` | Search paths for Nim source files |
| `docstring_style` | `"rst"` | Docstring format: `rst`, `google`, `numpy`, `epydoc`, `auto` |
| `show_source` | `true` | Show source file and line numbers |
| `show_signature` | `true` | Show full procedure signatures |
| `show_pragmas` | `true` | Show pragma annotations like `{.raises.}` |
| `show_private` | `false` | Include non-exported (private) symbols |
| `heading_level` | `2` | Starting heading level for entries |
| `source_url` | `null` | Repository URL for source links (e.g., `https://github.com/user/repo`) |
See the [full documentation](https://elijahr.github.io/mkdocstrings-nim/) for more details.
## Projects Using mkdocstrings-nim
- [nim-typestates](https://github.com/elijahr/nim-typestates) - Compile-time state machine verification
- [lockfreequeues](https://github.com/elijahr/lockfreequeues) - Lock-free data structures for Nim
## License
MIT