emdg 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- emdg-0.1.0/LICENSE +21 -0
- emdg-0.1.0/PKG-INFO +332 -0
- emdg-0.1.0/README.md +321 -0
- emdg-0.1.0/emdg/__init__.py +14 -0
- emdg-0.1.0/emdg/__main__.py +3 -0
- emdg-0.1.0/emdg/cli.py +147 -0
- emdg-0.1.0/emdg/frontmatter.py +121 -0
- emdg-0.1.0/emdg/generator.py +696 -0
- emdg-0.1.0/emdg/main.py +0 -0
- emdg-0.1.0/emdg/scanner.py +178 -0
- emdg-0.1.0/emdg.egg-info/PKG-INFO +332 -0
- emdg-0.1.0/emdg.egg-info/SOURCES.txt +20 -0
- emdg-0.1.0/emdg.egg-info/dependency_links.txt +1 -0
- emdg-0.1.0/emdg.egg-info/entry_points.txt +2 -0
- emdg-0.1.0/emdg.egg-info/requires.txt +3 -0
- emdg-0.1.0/emdg.egg-info/top_level.txt +1 -0
- emdg-0.1.0/pyproject.toml +20 -0
- emdg-0.1.0/setup.cfg +4 -0
- emdg-0.1.0/tests/test_cli.py +104 -0
- emdg-0.1.0/tests/test_frontmatter.py +71 -0
- emdg-0.1.0/tests/test_generator.py +151 -0
- emdg-0.1.0/tests/test_scanner.py +130 -0
emdg-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lucas
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
emdg-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,332 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: emdg
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Generate a single-page HTML documentation site from Markdown
|
|
5
|
+
Requires-Python: >=3.13
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Provides-Extra: test
|
|
9
|
+
Requires-Dist: pytest>=9.2.0; extra == "test"
|
|
10
|
+
Dynamic: license-file
|
|
11
|
+
|
|
12
|
+
# emdg
|
|
13
|
+
|
|
14
|
+
`emdg` (Easy Markdown Docs Generator) scans Markdown files and builds a single
|
|
15
|
+
HTML documentation site. It uses convention over configuration: folders become
|
|
16
|
+
sections, filenames become page titles, and optional frontmatter customizes
|
|
17
|
+
pages and sections.
|
|
18
|
+
|
|
19
|
+
## Features
|
|
20
|
+
|
|
21
|
+
- One command to build a searchable, hash-routed documentation site.
|
|
22
|
+
- Nested folders become nested sidebar sections.
|
|
23
|
+
- Optional frontmatter for page titles, order, descriptions, tags, drafts, and
|
|
24
|
+
section metadata.
|
|
25
|
+
- Light, dark, and system-preference themes.
|
|
26
|
+
- Optional local HTTP server and automatic rebuild mode.
|
|
27
|
+
- No third-party Python runtime dependencies.
|
|
28
|
+
|
|
29
|
+
## Requirements and installation
|
|
30
|
+
|
|
31
|
+
Python 3.13 or newer is required.
|
|
32
|
+
|
|
33
|
+
Install the published package:
|
|
34
|
+
|
|
35
|
+
```console
|
|
36
|
+
pip install emdg
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Then run it from any directory:
|
|
40
|
+
|
|
41
|
+
```console
|
|
42
|
+
emdg --help
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
To install an editable checkout with the test dependency:
|
|
46
|
+
|
|
47
|
+
```console
|
|
48
|
+
python -m pip install -e ".[test]"
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## AI agent skill
|
|
52
|
+
|
|
53
|
+
The [emdg documentation skill](docs/skills/SKILL.md) guides AI agents in
|
|
54
|
+
organizing docs and using the CLI, including frontmatter and build workflows.
|
|
55
|
+
|
|
56
|
+
## Quick start
|
|
57
|
+
|
|
58
|
+
Given a project like:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
my-project/
|
|
62
|
+
├── docs/
|
|
63
|
+
│ ├── overview.md
|
|
64
|
+
│ ├── getting-started/
|
|
65
|
+
│ │ ├── _section.md
|
|
66
|
+
│ │ ├── install.md
|
|
67
|
+
│ │ └── first-steps.md
|
|
68
|
+
│ └── reference/
|
|
69
|
+
│ └── commands.md
|
|
70
|
+
└── ...
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Build the site:
|
|
74
|
+
|
|
75
|
+
```console
|
|
76
|
+
emdg docs
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
This scans `docs/` and writes `docs.html` to the **current working directory**.
|
|
80
|
+
The output location is independent of the source directory. Root-level Markdown
|
|
81
|
+
files appear first in the sidebar, except for a root-level `README.md`: it is
|
|
82
|
+
the site's home page, opens by default, and is omitted from the sidebar. Clicking
|
|
83
|
+
the site title returns to that page. Folders become sections, with deeper folders
|
|
84
|
+
becoming subsections.
|
|
85
|
+
|
|
86
|
+
The page title defaults to the source directory name (`docs` becomes `Docs`).
|
|
87
|
+
Filenames and folder names are humanized by replacing hyphens and underscores
|
|
88
|
+
with spaces and capitalizing words (`getting-started` becomes `Getting Started`).
|
|
89
|
+
Frontmatter can override a Markdown page's display title.
|
|
90
|
+
|
|
91
|
+
## Command-line reference
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
emdg [source] [-o OUTPUT] [-t TITLE] [-i NAME]... [--theme auto|light|dark]
|
|
95
|
+
[--serve] [--watch] [-v]
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
| Option | Default | Description |
|
|
99
|
+
| --- | --- | --- |
|
|
100
|
+
| `source` | `.` | Directory to scan recursively. It must exist and be a directory. |
|
|
101
|
+
| `-o`, `--output` | `docs.html` | Output HTML file. Relative paths are resolved from the current working directory; its parent directory must already exist. |
|
|
102
|
+
| `-t`, `--title` | Humanized source directory name | Site title shown in the browser tab and interface. |
|
|
103
|
+
| `-i`, `--ignore NAME` | Built-in ignores | Ignore a file or directory by name. Repeat the option for multiple names. Names are matched anywhere in the source tree, not as paths. |
|
|
104
|
+
| `--theme` | `auto` | Initial theme: `auto` follows the browser's system preference, or choose `light` or `dark`. A theme already saved in that browser takes precedence. |
|
|
105
|
+
| `--serve` | Off | Serve the generated output on `http://127.0.0.1:8000/<output-filename>` until interrupted. |
|
|
106
|
+
| `--watch` | Off | Keep running and rebuild after Markdown files are added, removed, or changed. |
|
|
107
|
+
| `-v`, `--verbose` | Off | Print informational messages, including build and watch activity. |
|
|
108
|
+
| `-h`, `--help` | — | Show command help. |
|
|
109
|
+
|
|
110
|
+
Examples:
|
|
111
|
+
|
|
112
|
+
```console
|
|
113
|
+
# Use the current directory and default output
|
|
114
|
+
emdg
|
|
115
|
+
|
|
116
|
+
# Give the site a name and choose the output path
|
|
117
|
+
emdg ./docs --output ./public/manual.html --title "Team Handbook"
|
|
118
|
+
|
|
119
|
+
# Exclude matching names wherever they occur in the source tree
|
|
120
|
+
emdg docs --ignore internal --ignore drafts
|
|
121
|
+
|
|
122
|
+
# Build using a light theme
|
|
123
|
+
emdg docs --theme light
|
|
124
|
+
|
|
125
|
+
# Serve the generated docs and rebuild when Markdown changes
|
|
126
|
+
emdg docs --output site.html --serve --watch
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The server binds to loopback (`127.0.0.1`) on fixed port `8000`; it is intended
|
|
130
|
+
for local preview, not as a public hosting server. Without `--watch`, `--serve`
|
|
131
|
+
serves the one build made when the command starts. With `--watch`, the CLI checks
|
|
132
|
+
for Markdown file changes about twice per second and rebuilds the same output.
|
|
133
|
+
Press `Ctrl+C` to stop serving or watching.
|
|
134
|
+
|
|
135
|
+
The built-in ignored directory names are `.git`, `.hg`, `.svn`, `.venv`, `venv`,
|
|
136
|
+
`__pycache__`, `node_modules`, `.idea`, `.vscode`, `dist`, and `build`. Any
|
|
137
|
+
dot-prefixed file or directory is also ignored automatically. Custom ignores
|
|
138
|
+
are additional name matches; they do not enable scanning hidden files.
|
|
139
|
+
|
|
140
|
+
The CLI scans `.md` files (case-insensitively). The Python scanning API can use
|
|
141
|
+
other extensions.
|
|
142
|
+
|
|
143
|
+
## Optional frontmatter
|
|
144
|
+
|
|
145
|
+
Frontmatter is a small YAML-like block at the very top of a Markdown file. It
|
|
146
|
+
starts with a line containing `---` and ends with a line containing `---` or
|
|
147
|
+
`...`. Everything after the closing line is the Markdown body; the delimiters
|
|
148
|
+
are removed before rendering.
|
|
149
|
+
|
|
150
|
+
```markdown
|
|
151
|
+
---
|
|
152
|
+
title: Cursor Pagination
|
|
153
|
+
emoji: 📄
|
|
154
|
+
order: 2
|
|
155
|
+
description: How cursor-based pagination works across endpoints.
|
|
156
|
+
tags: [api, pagination]
|
|
157
|
+
draft: false
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
# Cursor Pagination
|
|
161
|
+
|
|
162
|
+
Write the page content here.
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
All fields are optional. Without frontmatter, the file is still included and
|
|
166
|
+
its title is derived from its filename.
|
|
167
|
+
|
|
168
|
+
| Field | Type and default | Effect |
|
|
169
|
+
| --- | --- | --- |
|
|
170
|
+
| `title` | Text; filename-derived title | Overrides the page's sidebar label. It does not add a heading to the Markdown body. |
|
|
171
|
+
| `emoji` | Text; none | Prefixes the page's sidebar label. |
|
|
172
|
+
| `order` | Integer; `999` | Sorts pages or sections numerically in ascending order. Equal orders are sorted by title, case-insensitively, then by relative path. Lower numbers appear first; omitted or invalid values use `999`. |
|
|
173
|
+
| `description` | Text; none | Displays a short description above the page body. |
|
|
174
|
+
| `tags` | List of text; empty list | Displays tag badges and includes each tag in sidebar search. |
|
|
175
|
+
| `draft` | Boolean-like text; `false` | Excludes the page from the generated site when set to a recognized true value. |
|
|
176
|
+
|
|
177
|
+
### Frontmatter value syntax
|
|
178
|
+
|
|
179
|
+
This is a deliberately small parser, not a full YAML implementation:
|
|
180
|
+
|
|
181
|
+
- Values can be unquoted, single-quoted, or double-quoted. Matching outer
|
|
182
|
+
quotes are removed; YAML escape sequences and nested objects are not parsed.
|
|
183
|
+
- `order` must be an integer. A non-integer value leaves the default order
|
|
184
|
+
(`999`) in effect.
|
|
185
|
+
- `draft: true`, `draft: yes`, `draft: 1`, and `draft: on` are treated as true,
|
|
186
|
+
case-insensitively. Other values, including `false`, are false.
|
|
187
|
+
- Tags can be written inline or as a block list:
|
|
188
|
+
|
|
189
|
+
```yaml
|
|
190
|
+
tags: [api, "getting started"]
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
```yaml
|
|
194
|
+
tags:
|
|
195
|
+
- api
|
|
196
|
+
- getting started
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
- Blank lines and lines beginning with `#` inside the frontmatter are ignored.
|
|
200
|
+
- Unknown keys are accepted by the parser but do not change the generated
|
|
201
|
+
documentation.
|
|
202
|
+
- If the opening delimiter is missing or there is no closing delimiter, the
|
|
203
|
+
content is treated as ordinary Markdown instead of being partially removed.
|
|
204
|
+
|
|
205
|
+
### Section metadata files
|
|
206
|
+
|
|
207
|
+
To customize a folder's sidebar section, put `_section.md` or `index.md` in that
|
|
208
|
+
folder and add frontmatter:
|
|
209
|
+
|
|
210
|
+
```text
|
|
211
|
+
docs/
|
|
212
|
+
└── getting-started/
|
|
213
|
+
├── _section.md
|
|
214
|
+
├── install.md
|
|
215
|
+
└── first-steps.md
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
```markdown
|
|
219
|
+
---
|
|
220
|
+
title: Start Here
|
|
221
|
+
emoji: 🚀
|
|
222
|
+
order: 1
|
|
223
|
+
description: Installation and first steps.
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
# Start Here
|
|
227
|
+
|
|
228
|
+
This content appears when the section is selected.
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
The `title`, `emoji`, and `order` values customize the section's sidebar label
|
|
232
|
+
and position. `_section.md` takes precedence over `index.md` if both exist.
|
|
233
|
+
These helper files are reserved and are not rendered as pages; an `index.md`
|
|
234
|
+
body is not used as a landing page. Markdown after `_section.md`'s frontmatter
|
|
235
|
+
is displayed as the section's landing content when its sidebar heading is
|
|
236
|
+
selected. If `_section.md` has no body, the heading only expands the navigation.
|
|
237
|
+
A section's frontmatter description is shown above its landing content when
|
|
238
|
+
present. A folder is shown only when it contains at least one non-draft
|
|
239
|
+
Markdown page somewhere below it.
|
|
240
|
+
|
|
241
|
+
## Generated site behavior
|
|
242
|
+
|
|
243
|
+
- The output is one HTML file containing the scanned Markdown content and
|
|
244
|
+
client-side page data. Navigation changes the URL hash; it does not fetch
|
|
245
|
+
Markdown files after generation.
|
|
246
|
+
- The sidebar search filters on page title, Markdown body text, and tags.
|
|
247
|
+
- Sidebar sections and subsections are collapsible and start closed. The section
|
|
248
|
+
containing the current page opens automatically; searching opens sections
|
|
249
|
+
with matching results.
|
|
250
|
+
- If a section has Markdown body content in `_section.md`, selecting its heading
|
|
251
|
+
displays that content in the main pane as a section landing page.
|
|
252
|
+
- The home page footer shows when the site was generated, using a UTC timestamp.
|
|
253
|
+
- Pages with `##` or `###` headings get an automatic "On this page" table of
|
|
254
|
+
contents with in-page links.
|
|
255
|
+
- GitHub-style blockquote callouts are supported: `[!NOTE]`, `[!TIP]`,
|
|
256
|
+
`[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`. Their styling and the table of
|
|
257
|
+
contents are implemented inline; they add no CDN dependencies.
|
|
258
|
+
- The selected page's description and tags appear above its content.
|
|
259
|
+
- A saved theme choice is kept in browser `localStorage` under `emdg-theme`.
|
|
260
|
+
This saved choice takes precedence over the generated `--theme` default.
|
|
261
|
+
- Standard Markdown is rendered in the browser by Marked. Fenced code blocks
|
|
262
|
+
are highlighted by Highlight.js; `mermaid` fenced blocks are rendered as
|
|
263
|
+
diagrams by Mermaid.
|
|
264
|
+
- Tailwind CSS, Marked, Highlight.js, and Mermaid load from public CDNs. An
|
|
265
|
+
internet connection is required for the complete styling and rendering
|
|
266
|
+
experience.
|
|
267
|
+
- The Markdown renderer supports raw HTML. Only build and publish documentation
|
|
268
|
+
from sources you trust.
|
|
269
|
+
|
|
270
|
+
## Python API
|
|
271
|
+
|
|
272
|
+
```python
|
|
273
|
+
from emdg import generate_html, scan_docs
|
|
274
|
+
|
|
275
|
+
result = scan_docs(
|
|
276
|
+
"docs",
|
|
277
|
+
ignore={"internal"},
|
|
278
|
+
extensions={".md", ".markdown"},
|
|
279
|
+
)
|
|
280
|
+
output = generate_html(
|
|
281
|
+
result,
|
|
282
|
+
"public/docs.html",
|
|
283
|
+
title="Team Handbook",
|
|
284
|
+
theme="dark",
|
|
285
|
+
)
|
|
286
|
+
print(output)
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
### `scan_docs`
|
|
290
|
+
|
|
291
|
+
```python
|
|
292
|
+
scan_docs(origin, *, ignore=None, extensions=(".md",))
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
- `origin` is a directory path (`str` or `pathlib.Path`).
|
|
296
|
+
- `ignore` is an optional iterable of exact file/directory names to exclude.
|
|
297
|
+
Built-in ignores and the automatic dotfile exclusion still apply.
|
|
298
|
+
- `extensions` is an iterable of extensions, with or without the leading dot.
|
|
299
|
+
Matching is case-insensitive.
|
|
300
|
+
- Returns a `ScanResult` with an optional root `home` page, other `root_items`,
|
|
301
|
+
and nested `sections`. A root-level `README.md` becomes `home` and is not
|
|
302
|
+
included in `root_items`; a README inside a section remains a normal page.
|
|
303
|
+
- Each `DocItem` stores its title, slug, absolute file path, relative path,
|
|
304
|
+
emoji, order, description, and tags. Each `DocSection` stores the
|
|
305
|
+
section metadata, optional Markdown body, items, and subsections.
|
|
306
|
+
- Raises `FileNotFoundError` if the origin does not exist and
|
|
307
|
+
`NotADirectoryError` if it is not a directory.
|
|
308
|
+
|
|
309
|
+
### `generate_html`
|
|
310
|
+
|
|
311
|
+
```python
|
|
312
|
+
generate_html(scan_result, output_path="docs.html", *, title=None, theme="auto")
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
- `scan_result` is the result of `scan_docs`.
|
|
316
|
+
- `output_path` is the HTML file path; its parent directory must exist.
|
|
317
|
+
- `title` overrides the site title. By default, the scan root's directory name
|
|
318
|
+
is humanized.
|
|
319
|
+
- `theme` must be `auto`, `light`, or `dark`.
|
|
320
|
+
- Writes UTF-8 HTML and returns the resolved output `Path`.
|
|
321
|
+
|
|
322
|
+
The public package also exports `Frontmatter`, `DocItem`, `DocSection`,
|
|
323
|
+
`ScanResult`, `parse_frontmatter`, and `humanize_name`.
|
|
324
|
+
|
|
325
|
+
## Development
|
|
326
|
+
|
|
327
|
+
Install the optional test dependency and run the test suite:
|
|
328
|
+
|
|
329
|
+
```console
|
|
330
|
+
python -m pip install -e ".[test]"
|
|
331
|
+
python -m pytest
|
|
332
|
+
```
|
emdg-0.1.0/README.md
ADDED
|
@@ -0,0 +1,321 @@
|
|
|
1
|
+
# emdg
|
|
2
|
+
|
|
3
|
+
`emdg` (Easy Markdown Docs Generator) scans Markdown files and builds a single
|
|
4
|
+
HTML documentation site. It uses convention over configuration: folders become
|
|
5
|
+
sections, filenames become page titles, and optional frontmatter customizes
|
|
6
|
+
pages and sections.
|
|
7
|
+
|
|
8
|
+
## Features
|
|
9
|
+
|
|
10
|
+
- One command to build a searchable, hash-routed documentation site.
|
|
11
|
+
- Nested folders become nested sidebar sections.
|
|
12
|
+
- Optional frontmatter for page titles, order, descriptions, tags, drafts, and
|
|
13
|
+
section metadata.
|
|
14
|
+
- Light, dark, and system-preference themes.
|
|
15
|
+
- Optional local HTTP server and automatic rebuild mode.
|
|
16
|
+
- No third-party Python runtime dependencies.
|
|
17
|
+
|
|
18
|
+
## Requirements and installation
|
|
19
|
+
|
|
20
|
+
Python 3.13 or newer is required.
|
|
21
|
+
|
|
22
|
+
Install the published package:
|
|
23
|
+
|
|
24
|
+
```console
|
|
25
|
+
pip install emdg
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Then run it from any directory:
|
|
29
|
+
|
|
30
|
+
```console
|
|
31
|
+
emdg --help
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
To install an editable checkout with the test dependency:
|
|
35
|
+
|
|
36
|
+
```console
|
|
37
|
+
python -m pip install -e ".[test]"
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## AI agent skill
|
|
41
|
+
|
|
42
|
+
The [emdg documentation skill](docs/skills/SKILL.md) guides AI agents in
|
|
43
|
+
organizing docs and using the CLI, including frontmatter and build workflows.
|
|
44
|
+
|
|
45
|
+
## Quick start
|
|
46
|
+
|
|
47
|
+
Given a project like:
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
my-project/
|
|
51
|
+
├── docs/
|
|
52
|
+
│ ├── overview.md
|
|
53
|
+
│ ├── getting-started/
|
|
54
|
+
│ │ ├── _section.md
|
|
55
|
+
│ │ ├── install.md
|
|
56
|
+
│ │ └── first-steps.md
|
|
57
|
+
│ └── reference/
|
|
58
|
+
│ └── commands.md
|
|
59
|
+
└── ...
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Build the site:
|
|
63
|
+
|
|
64
|
+
```console
|
|
65
|
+
emdg docs
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
This scans `docs/` and writes `docs.html` to the **current working directory**.
|
|
69
|
+
The output location is independent of the source directory. Root-level Markdown
|
|
70
|
+
files appear first in the sidebar, except for a root-level `README.md`: it is
|
|
71
|
+
the site's home page, opens by default, and is omitted from the sidebar. Clicking
|
|
72
|
+
the site title returns to that page. Folders become sections, with deeper folders
|
|
73
|
+
becoming subsections.
|
|
74
|
+
|
|
75
|
+
The page title defaults to the source directory name (`docs` becomes `Docs`).
|
|
76
|
+
Filenames and folder names are humanized by replacing hyphens and underscores
|
|
77
|
+
with spaces and capitalizing words (`getting-started` becomes `Getting Started`).
|
|
78
|
+
Frontmatter can override a Markdown page's display title.
|
|
79
|
+
|
|
80
|
+
## Command-line reference
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
emdg [source] [-o OUTPUT] [-t TITLE] [-i NAME]... [--theme auto|light|dark]
|
|
84
|
+
[--serve] [--watch] [-v]
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
| Option | Default | Description |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| `source` | `.` | Directory to scan recursively. It must exist and be a directory. |
|
|
90
|
+
| `-o`, `--output` | `docs.html` | Output HTML file. Relative paths are resolved from the current working directory; its parent directory must already exist. |
|
|
91
|
+
| `-t`, `--title` | Humanized source directory name | Site title shown in the browser tab and interface. |
|
|
92
|
+
| `-i`, `--ignore NAME` | Built-in ignores | Ignore a file or directory by name. Repeat the option for multiple names. Names are matched anywhere in the source tree, not as paths. |
|
|
93
|
+
| `--theme` | `auto` | Initial theme: `auto` follows the browser's system preference, or choose `light` or `dark`. A theme already saved in that browser takes precedence. |
|
|
94
|
+
| `--serve` | Off | Serve the generated output on `http://127.0.0.1:8000/<output-filename>` until interrupted. |
|
|
95
|
+
| `--watch` | Off | Keep running and rebuild after Markdown files are added, removed, or changed. |
|
|
96
|
+
| `-v`, `--verbose` | Off | Print informational messages, including build and watch activity. |
|
|
97
|
+
| `-h`, `--help` | — | Show command help. |
|
|
98
|
+
|
|
99
|
+
Examples:
|
|
100
|
+
|
|
101
|
+
```console
|
|
102
|
+
# Use the current directory and default output
|
|
103
|
+
emdg
|
|
104
|
+
|
|
105
|
+
# Give the site a name and choose the output path
|
|
106
|
+
emdg ./docs --output ./public/manual.html --title "Team Handbook"
|
|
107
|
+
|
|
108
|
+
# Exclude matching names wherever they occur in the source tree
|
|
109
|
+
emdg docs --ignore internal --ignore drafts
|
|
110
|
+
|
|
111
|
+
# Build using a light theme
|
|
112
|
+
emdg docs --theme light
|
|
113
|
+
|
|
114
|
+
# Serve the generated docs and rebuild when Markdown changes
|
|
115
|
+
emdg docs --output site.html --serve --watch
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The server binds to loopback (`127.0.0.1`) on fixed port `8000`; it is intended
|
|
119
|
+
for local preview, not as a public hosting server. Without `--watch`, `--serve`
|
|
120
|
+
serves the one build made when the command starts. With `--watch`, the CLI checks
|
|
121
|
+
for Markdown file changes about twice per second and rebuilds the same output.
|
|
122
|
+
Press `Ctrl+C` to stop serving or watching.
|
|
123
|
+
|
|
124
|
+
The built-in ignored directory names are `.git`, `.hg`, `.svn`, `.venv`, `venv`,
|
|
125
|
+
`__pycache__`, `node_modules`, `.idea`, `.vscode`, `dist`, and `build`. Any
|
|
126
|
+
dot-prefixed file or directory is also ignored automatically. Custom ignores
|
|
127
|
+
are additional name matches; they do not enable scanning hidden files.
|
|
128
|
+
|
|
129
|
+
The CLI scans `.md` files (case-insensitively). The Python scanning API can use
|
|
130
|
+
other extensions.
|
|
131
|
+
|
|
132
|
+
## Optional frontmatter
|
|
133
|
+
|
|
134
|
+
Frontmatter is a small YAML-like block at the very top of a Markdown file. It
|
|
135
|
+
starts with a line containing `---` and ends with a line containing `---` or
|
|
136
|
+
`...`. Everything after the closing line is the Markdown body; the delimiters
|
|
137
|
+
are removed before rendering.
|
|
138
|
+
|
|
139
|
+
```markdown
|
|
140
|
+
---
|
|
141
|
+
title: Cursor Pagination
|
|
142
|
+
emoji: 📄
|
|
143
|
+
order: 2
|
|
144
|
+
description: How cursor-based pagination works across endpoints.
|
|
145
|
+
tags: [api, pagination]
|
|
146
|
+
draft: false
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
# Cursor Pagination
|
|
150
|
+
|
|
151
|
+
Write the page content here.
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
All fields are optional. Without frontmatter, the file is still included and
|
|
155
|
+
its title is derived from its filename.
|
|
156
|
+
|
|
157
|
+
| Field | Type and default | Effect |
|
|
158
|
+
| --- | --- | --- |
|
|
159
|
+
| `title` | Text; filename-derived title | Overrides the page's sidebar label. It does not add a heading to the Markdown body. |
|
|
160
|
+
| `emoji` | Text; none | Prefixes the page's sidebar label. |
|
|
161
|
+
| `order` | Integer; `999` | Sorts pages or sections numerically in ascending order. Equal orders are sorted by title, case-insensitively, then by relative path. Lower numbers appear first; omitted or invalid values use `999`. |
|
|
162
|
+
| `description` | Text; none | Displays a short description above the page body. |
|
|
163
|
+
| `tags` | List of text; empty list | Displays tag badges and includes each tag in sidebar search. |
|
|
164
|
+
| `draft` | Boolean-like text; `false` | Excludes the page from the generated site when set to a recognized true value. |
|
|
165
|
+
|
|
166
|
+
### Frontmatter value syntax
|
|
167
|
+
|
|
168
|
+
This is a deliberately small parser, not a full YAML implementation:
|
|
169
|
+
|
|
170
|
+
- Values can be unquoted, single-quoted, or double-quoted. Matching outer
|
|
171
|
+
quotes are removed; YAML escape sequences and nested objects are not parsed.
|
|
172
|
+
- `order` must be an integer. A non-integer value leaves the default order
|
|
173
|
+
(`999`) in effect.
|
|
174
|
+
- `draft: true`, `draft: yes`, `draft: 1`, and `draft: on` are treated as true,
|
|
175
|
+
case-insensitively. Other values, including `false`, are false.
|
|
176
|
+
- Tags can be written inline or as a block list:
|
|
177
|
+
|
|
178
|
+
```yaml
|
|
179
|
+
tags: [api, "getting started"]
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
```yaml
|
|
183
|
+
tags:
|
|
184
|
+
- api
|
|
185
|
+
- getting started
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
- Blank lines and lines beginning with `#` inside the frontmatter are ignored.
|
|
189
|
+
- Unknown keys are accepted by the parser but do not change the generated
|
|
190
|
+
documentation.
|
|
191
|
+
- If the opening delimiter is missing or there is no closing delimiter, the
|
|
192
|
+
content is treated as ordinary Markdown instead of being partially removed.
|
|
193
|
+
|
|
194
|
+
### Section metadata files
|
|
195
|
+
|
|
196
|
+
To customize a folder's sidebar section, put `_section.md` or `index.md` in that
|
|
197
|
+
folder and add frontmatter:
|
|
198
|
+
|
|
199
|
+
```text
|
|
200
|
+
docs/
|
|
201
|
+
└── getting-started/
|
|
202
|
+
├── _section.md
|
|
203
|
+
├── install.md
|
|
204
|
+
└── first-steps.md
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
```markdown
|
|
208
|
+
---
|
|
209
|
+
title: Start Here
|
|
210
|
+
emoji: 🚀
|
|
211
|
+
order: 1
|
|
212
|
+
description: Installation and first steps.
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
# Start Here
|
|
216
|
+
|
|
217
|
+
This content appears when the section is selected.
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
The `title`, `emoji`, and `order` values customize the section's sidebar label
|
|
221
|
+
and position. `_section.md` takes precedence over `index.md` if both exist.
|
|
222
|
+
These helper files are reserved and are not rendered as pages; an `index.md`
|
|
223
|
+
body is not used as a landing page. Markdown after `_section.md`'s frontmatter
|
|
224
|
+
is displayed as the section's landing content when its sidebar heading is
|
|
225
|
+
selected. If `_section.md` has no body, the heading only expands the navigation.
|
|
226
|
+
A section's frontmatter description is shown above its landing content when
|
|
227
|
+
present. A folder is shown only when it contains at least one non-draft
|
|
228
|
+
Markdown page somewhere below it.
|
|
229
|
+
|
|
230
|
+
## Generated site behavior
|
|
231
|
+
|
|
232
|
+
- The output is one HTML file containing the scanned Markdown content and
|
|
233
|
+
client-side page data. Navigation changes the URL hash; it does not fetch
|
|
234
|
+
Markdown files after generation.
|
|
235
|
+
- The sidebar search filters on page title, Markdown body text, and tags.
|
|
236
|
+
- Sidebar sections and subsections are collapsible and start closed. The section
|
|
237
|
+
containing the current page opens automatically; searching opens sections
|
|
238
|
+
with matching results.
|
|
239
|
+
- If a section has Markdown body content in `_section.md`, selecting its heading
|
|
240
|
+
displays that content in the main pane as a section landing page.
|
|
241
|
+
- The home page footer shows when the site was generated, using a UTC timestamp.
|
|
242
|
+
- Pages with `##` or `###` headings get an automatic "On this page" table of
|
|
243
|
+
contents with in-page links.
|
|
244
|
+
- GitHub-style blockquote callouts are supported: `[!NOTE]`, `[!TIP]`,
|
|
245
|
+
`[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`. Their styling and the table of
|
|
246
|
+
contents are implemented inline; they add no CDN dependencies.
|
|
247
|
+
- The selected page's description and tags appear above its content.
|
|
248
|
+
- A saved theme choice is kept in browser `localStorage` under `emdg-theme`.
|
|
249
|
+
This saved choice takes precedence over the generated `--theme` default.
|
|
250
|
+
- Standard Markdown is rendered in the browser by Marked. Fenced code blocks
|
|
251
|
+
are highlighted by Highlight.js; `mermaid` fenced blocks are rendered as
|
|
252
|
+
diagrams by Mermaid.
|
|
253
|
+
- Tailwind CSS, Marked, Highlight.js, and Mermaid load from public CDNs. An
|
|
254
|
+
internet connection is required for the complete styling and rendering
|
|
255
|
+
experience.
|
|
256
|
+
- The Markdown renderer supports raw HTML. Only build and publish documentation
|
|
257
|
+
from sources you trust.
|
|
258
|
+
|
|
259
|
+
## Python API
|
|
260
|
+
|
|
261
|
+
```python
|
|
262
|
+
from emdg import generate_html, scan_docs
|
|
263
|
+
|
|
264
|
+
result = scan_docs(
|
|
265
|
+
"docs",
|
|
266
|
+
ignore={"internal"},
|
|
267
|
+
extensions={".md", ".markdown"},
|
|
268
|
+
)
|
|
269
|
+
output = generate_html(
|
|
270
|
+
result,
|
|
271
|
+
"public/docs.html",
|
|
272
|
+
title="Team Handbook",
|
|
273
|
+
theme="dark",
|
|
274
|
+
)
|
|
275
|
+
print(output)
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
### `scan_docs`
|
|
279
|
+
|
|
280
|
+
```python
|
|
281
|
+
scan_docs(origin, *, ignore=None, extensions=(".md",))
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
- `origin` is a directory path (`str` or `pathlib.Path`).
|
|
285
|
+
- `ignore` is an optional iterable of exact file/directory names to exclude.
|
|
286
|
+
Built-in ignores and the automatic dotfile exclusion still apply.
|
|
287
|
+
- `extensions` is an iterable of extensions, with or without the leading dot.
|
|
288
|
+
Matching is case-insensitive.
|
|
289
|
+
- Returns a `ScanResult` with an optional root `home` page, other `root_items`,
|
|
290
|
+
and nested `sections`. A root-level `README.md` becomes `home` and is not
|
|
291
|
+
included in `root_items`; a README inside a section remains a normal page.
|
|
292
|
+
- Each `DocItem` stores its title, slug, absolute file path, relative path,
|
|
293
|
+
emoji, order, description, and tags. Each `DocSection` stores the
|
|
294
|
+
section metadata, optional Markdown body, items, and subsections.
|
|
295
|
+
- Raises `FileNotFoundError` if the origin does not exist and
|
|
296
|
+
`NotADirectoryError` if it is not a directory.
|
|
297
|
+
|
|
298
|
+
### `generate_html`
|
|
299
|
+
|
|
300
|
+
```python
|
|
301
|
+
generate_html(scan_result, output_path="docs.html", *, title=None, theme="auto")
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
- `scan_result` is the result of `scan_docs`.
|
|
305
|
+
- `output_path` is the HTML file path; its parent directory must exist.
|
|
306
|
+
- `title` overrides the site title. By default, the scan root's directory name
|
|
307
|
+
is humanized.
|
|
308
|
+
- `theme` must be `auto`, `light`, or `dark`.
|
|
309
|
+
- Writes UTF-8 HTML and returns the resolved output `Path`.
|
|
310
|
+
|
|
311
|
+
The public package also exports `Frontmatter`, `DocItem`, `DocSection`,
|
|
312
|
+
`ScanResult`, `parse_frontmatter`, and `humanize_name`.
|
|
313
|
+
|
|
314
|
+
## Development
|
|
315
|
+
|
|
316
|
+
Install the optional test dependency and run the test suite:
|
|
317
|
+
|
|
318
|
+
```console
|
|
319
|
+
python -m pip install -e ".[test]"
|
|
320
|
+
python -m pytest
|
|
321
|
+
```
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
from emdg.frontmatter import Frontmatter, parse_frontmatter
|
|
2
|
+
from emdg.generator import generate_html
|
|
3
|
+
from emdg.scanner import DocItem, DocSection, ScanResult, humanize_name, scan_docs
|
|
4
|
+
|
|
5
|
+
__all__ = [
|
|
6
|
+
"DocItem",
|
|
7
|
+
"DocSection",
|
|
8
|
+
"Frontmatter",
|
|
9
|
+
"ScanResult",
|
|
10
|
+
"generate_html",
|
|
11
|
+
"humanize_name",
|
|
12
|
+
"parse_frontmatter",
|
|
13
|
+
"scan_docs",
|
|
14
|
+
]
|