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 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
+ ]
@@ -0,0 +1,3 @@
1
+ from emdg.cli import main
2
+
3
+ raise SystemExit(main())