mkforge 0.2.0__tar.gz → 0.3.0__tar.gz

{mkforge-0.2.0 → mkforge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkforge
-Version: 0.2.0
+Version: 0.3.0
 Summary: Programmatic Markdown report generation for Python.
 Project-URL: Homepage, https://github.com/antoinebarre/mkforge
 Project-URL: Repository, https://github.com/antoinebarre/mkforge
@@ -161,6 +161,27 @@ collapsed to a single hyphen, leading/trailing hyphens trimmed. Unicode
 letters are preserved (case-folded, not transliterated), which keeps slugs
 consistent with the anchors GitHub generates for the same heading.
 
+## Heading Numbering
+
+```python
+from mkforge import renumber_markdown_headings, strip_markdown_heading_numbering
+
+markdown = "# 9. Document\n## 4. Titre 1\n### 8. Tritre niveau 2\n"
+
+strip_markdown_heading_numbering(markdown)
+# "# Document\n## Titre 1\n### Tritre niveau 2\n"
+
+renumber_markdown_headings(markdown, start_level=2)
+# "# Document\n## 1. Titre 1\n### 1.1. Tritre niveau 2\n"
+```
+
+`strip_markdown_heading_numbering` and `renumber_markdown_headings` are pure
+Markdown helpers for doc-as-code pipelines. They modify only ATX headings
+outside fenced code blocks, preserve heading levels, and can start numbering
+at a chosen level with `start_level`. Use `first_number` to start a fragment
+at a later number, and `separator` to control the text between number and
+title.
+
 ## Relationship With Scribpy
 
 MkForge is intended to be independent from Scribpy.

{mkforge-0.2.0 → mkforge-0.3.0}/README.md

@@ -146,6 +146,27 @@ collapsed to a single hyphen, leading/trailing hyphens trimmed. Unicode
 letters are preserved (case-folded, not transliterated), which keeps slugs
 consistent with the anchors GitHub generates for the same heading.
 
+## Heading Numbering
+
+```python
+from mkforge import renumber_markdown_headings, strip_markdown_heading_numbering
+
+markdown = "# 9. Document\n## 4. Titre 1\n### 8. Tritre niveau 2\n"
+
+strip_markdown_heading_numbering(markdown)
+# "# Document\n## Titre 1\n### Tritre niveau 2\n"
+
+renumber_markdown_headings(markdown, start_level=2)
+# "# Document\n## 1. Titre 1\n### 1.1. Tritre niveau 2\n"
+```
+
+`strip_markdown_heading_numbering` and `renumber_markdown_headings` are pure
+Markdown helpers for doc-as-code pipelines. They modify only ATX headings
+outside fenced code blocks, preserve heading levels, and can start numbering
+at a chosen level with `start_level`. Use `first_number` to start a fragment
+at a later number, and `separator` to control the text between number and
+title.
+
 ## Relationship With Scribpy
 
 MkForge is intended to be independent from Scribpy.

{mkforge-0.2.0 → mkforge-0.3.0}/docs/API_REFERENCE.md

@@ -21,7 +21,10 @@ from mkforge import (
     Report,
     Section,
     Table,
+    renumber_markdown_headings,
     slugify_heading,
+    strip_heading_numbering_text,
+    strip_markdown_heading_numbering,
     validate_markdown_chapters,
     validate_markdown_headings,
     validate_markdown_images,
@@ -97,6 +100,9 @@ Module-level helpers are documented for advanced integrations and tests.
 | `validate_markdown_headings` | `mkforge` | validation | Check level/title heading contract |
 | `validate_markdown_images` | `mkforge` | validation/assets | Check Markdown image targets |
 | `slugify_heading` | `mkforge` | text | Convert a heading title to a GitHub-style anchor slug |
+| `strip_heading_numbering_text` | `mkforge` | text | Remove a numeric prefix from heading text |
+| `strip_markdown_heading_numbering` | `mkforge` | text | Remove numeric prefixes from ATX headings |
+| `renumber_markdown_headings` | `mkforge` | text | Rebuild ATX heading numbering by hierarchy |
 | `InvalidChildError` | `mkforge` | errors | Unsupported report-tree child |
 | `InvalidTableError` | `mkforge` | errors | Invalid table shape |
 | `ReportDepthError` | `mkforge` | errors | Section nesting below H6 |
@@ -1108,6 +1114,176 @@ separator). Use `slugify_heading` for anchors shared with external tools;
 
 ---
 
+## 6.8 `mkforge.heading_numbering` Helpers
+
+These helpers normalize numeric prefixes on Markdown headings. They are pure,
+deterministic, perform no I/O, and are useful for doc-as-code assemblers that
+merge Markdown fragments before publishing.
+
+All document-level helpers:
+
+- modify only ATX headings (`#` through `######`);
+- ignore fenced code blocks;
+- preserve non-heading lines;
+- preserve heading levels;
+- strip old numeric prefixes before adding new ones.
+
+### 6.8.1 `strip_heading_numbering_text`
+
+Module: `mkforge.heading_numbering`
+
+Exported by: `mkforge`
+
+Signature:
+
+```python
+strip_heading_numbering_text(text: str) -> str
+```
+
+Removes one leading numeric heading prefix from a heading title.
+
+Examples:
+
+```python
+from mkforge import strip_heading_numbering_text
+
+strip_heading_numbering_text("1. Introduction")     # "Introduction"
+strip_heading_numbering_text("1.2 Architecture")    # "Architecture"
+strip_heading_numbering_text("1.2.3 - Design")      # "Design"
+strip_heading_numbering_text("2026 Roadmap")        # "2026 Roadmap"
+strip_heading_numbering_text("Version 2.0")         # "Version 2.0"
+```
+
+Raises:
+
+| Condition | Exception |
+|---|---|
+| `text` is not a string | `TypeError` |
+
+### 6.8.2 `strip_markdown_heading_numbering`
+
+Module: `mkforge.heading_numbering`
+
+Exported by: `mkforge`
+
+Signature:
+
+```python
+strip_markdown_heading_numbering(markdown: str) -> str
+```
+
+Removes numeric prefixes from ATX headings in a complete Markdown document.
+
+Example:
+
+````python
+from mkforge import strip_markdown_heading_numbering
+
+markdown = """# 1. Introduction
+
+## 1.3 Architecture
+
+```python
+# 1. This must not change
+```
+"""
+
+strip_markdown_heading_numbering(markdown)
+````
+
+Result:
+
+````markdown
+# Introduction
+
+## Architecture
+
+```python
+# 1. This must not change
+```
+````
+
+Raises:
+
+| Condition | Exception |
+|---|---|
+| `markdown` is not a string | `TypeError` |
+
+### 6.8.3 `renumber_markdown_headings`
+
+Module: `mkforge.heading_numbering`
+
+Exported by: `mkforge`
+
+Signature:
+
+```python
+renumber_markdown_headings(
+    markdown: str,
+    *,
+    separator: str = ". ",
+    first_number: int = 1,
+    start_level: int = 1,
+) -> str
+```
+
+Removes old numeric prefixes from ATX headings, then generates coherent
+hierarchical numbering.
+
+Parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `markdown` | `str` | required | Markdown source text |
+| `separator` | `str` | `". "` | Text inserted between the number and title |
+| `first_number` | `int` | `1` | First number generated at the configured root level |
+| `start_level` | `int` | `1` | First heading level that receives generated numbering |
+
+Examples:
+
+```python
+from mkforge import renumber_markdown_headings
+
+renumber_markdown_headings("# 9. Intro\n## 4. Detail\n")
+# "# 1. Intro\n## 1.1. Detail\n"
+
+renumber_markdown_headings("# Intro\n## Detail\n", first_number=4)
+# "# 4. Intro\n## 4.1. Detail\n"
+
+renumber_markdown_headings("# Document\n## Titre\n### Détail\n", start_level=2)
+# "# Document\n## 1. Titre\n### 1.1. Détail\n"
+
+renumber_markdown_headings("## Titre\n### Détail\n", first_number=4, start_level=2)
+# "## 4. Titre\n### 4.1. Détail\n"
+```
+
+The `separator` controls only the text between the generated number and the
+title:
+
+| `separator` | Heading output |
+|---|---|
+| `". "` | `# 1. Title` |
+| `" "` | `# 1 Title` |
+| `" - "` | `# 1 - Title` |
+| `""` | `# 1Title` |
+
+When `start_level=2`, H1 headings are cleaned but not numbered. H2 headings
+become numeric roots (`1`, `2`, ...), and H3 headings become children
+(`1.1`, `1.2`, ...).
+
+Raises:
+
+| Condition | Exception |
+|---|---|
+| `markdown` is not a string | `TypeError` |
+| `separator` is not a string | `TypeError` |
+| `first_number` is not an integer | `TypeError` |
+| `start_level` is not an integer | `TypeError` |
+| `first_number` is less than 1 | `ValueError` |
+| `start_level` is outside 1-6 | `ValueError` |
+
+---
+
 ## 7. Metadata Reference
 
 Metadata is a free-form dictionary. MkForge does not define allowed keys.

{mkforge-0.2.0 → mkforge-0.3.0}/docs/USER_GUIDE.md

@@ -29,6 +29,7 @@ For exhaustive class, function, helper, rule, and feature contracts, see
 - [Verification](#verification)
 - [Validation](#validation)
 - [Heading Slugification](#heading-slugification)
+- [Heading Numbering](#heading-numbering)
 - [Assets](#assets)
 - [Errors](#errors)
 - [Patterns And Recommendations](#patterns-and-recommendations)
@@ -91,6 +92,16 @@ For heading anchor slugs:
 from mkforge import slugify_heading
 ```
 
+For cleaning and rebuilding Markdown heading numbering:
+
+```python
+from mkforge import (
+    renumber_markdown_headings,
+    strip_heading_numbering_text,
+    strip_markdown_heading_numbering,
+)
+```
+
 ## How To Think About MkForge
 
 MkForge has three jobs:
@@ -1009,6 +1020,78 @@ Behavior:
 This matches the anchors GitHub generates for the same heading text, so a
 link such as `[Analyse des Risques](#analyse-des-risques)` stays valid.
 
+## Heading Numbering
+
+Use the heading numbering helpers when a documentation pipeline assembles
+Markdown fragments and must clean or rebuild heading numbers before publishing.
+
+````python
+from mkforge import (
+    renumber_markdown_headings,
+    strip_markdown_heading_numbering,
+)
+
+markdown = """# 9. Document
+## 4. Titre 1
+### 8. Tritre niveau 2
+
+```markdown
+## 99. This must not change
+```
+"""
+
+strip_markdown_heading_numbering(markdown)
+renumber_markdown_headings(markdown, start_level=2)
+````
+
+With `start_level=2`, H1 headings are cleaned but not numbered, H2 headings
+become numeric roots, and H3 headings become their children:
+
+````markdown
+# Document
+## 1. Titre 1
+### 1.1. Tritre niveau 2
+
+```markdown
+## 99. This must not change
+```
+````
+
+The document-level helpers:
+
+- modify only ATX headings (`#` through `######`);
+- ignore fenced code blocks;
+- preserve non-heading lines;
+- preserve heading levels;
+- strip old numbering before adding new numbering.
+
+Use `first_number` when the fragment belongs later in a larger document:
+
+```python
+renumber_markdown_headings(markdown, first_number=4, start_level=2)
+```
+
+That starts numbering at the configured root level:
+
+```markdown
+## 4. Titre 1
+### 4.1. Tritre niveau 2
+```
+
+Use `separator` to control the text between the generated number and the
+title:
+
+```python
+renumber_markdown_headings(markdown, separator=" - ")
+```
+
+Examples:
+
+- `separator=". "` renders `# 1. Title`;
+- `separator=" "` renders `# 1 Title`;
+- `separator=" - "` renders `# 1 - Title`;
+- `separator=""` renders `# 1Title`.
+
 ## Assets
 
 MkForge treats image references carefully:

{mkforge-0.2.0 → mkforge-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mkforge"
-version = "0.2.0"
+version = "0.3.0"
 description = "Programmatic Markdown report generation for Python."
 readme = "README.md"
 requires-python = ">=3.12"

{mkforge-0.2.0 → mkforge-0.3.0}/src/mkforge/__init__.py

@@ -22,6 +22,11 @@ from mkforge.errors import (
     MissingAssetError,
     ReportDepthError,
 )
+from mkforge.heading_numbering import (
+    renumber_markdown_headings,
+    strip_heading_numbering_text,
+    strip_markdown_heading_numbering,
+)
 from mkforge.slugify import slugify_heading
 from mkforge.validation import (
     validate_markdown_chapters,
@@ -68,7 +73,10 @@ __all__ = [
     "Text",
     "VerificationReport",
     "VerificationSettings",
+    "renumber_markdown_headings",
     "slugify_heading",
+    "strip_heading_numbering_text",
+    "strip_markdown_heading_numbering",
     "validate_markdown_chapters",
     "validate_markdown_headings",
     "validate_markdown_images",
@@ -77,4 +85,4 @@ __all__ = [
     "verify_markdown_file",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"