simplibs-extractor-html 0.1.0__tar.gz

simplibs_extractor_html-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dalibor Sova (Sudip2708)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

simplibs_extractor_html-0.1.0/PKG-INFO

@@ -0,0 +1,504 @@
+Metadata-Version: 2.4
+Name: simplibs-extractor-html
+Version: 0.1.0
+Summary: The HTML add-on of simplibs-extractor: file rules for HTML pages and Django and Jinja templates, steps that remove comments and imports (found by a scanner that knows scripts, styles and template tags), an outline step and thirteen ready profiles.
+Author-email: "Dalibor Sova (Sudip2708)" <daliborsova@seznam.cz>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/simplibs/simplibs-extractor-html
+Project-URL: Repository, https://github.com/simplibs/simplibs-extractor-html
+Project-URL: Issues, https://github.com/simplibs/simplibs-extractor-html/issues
+Project-URL: Changelog, https://github.com/simplibs/simplibs-extractor-html/blob/main/CHANGELOG.md
+Keywords: extractor,html,django,jinja,templates,code-extractor,project-to-text,comments,imports,outline,markdown,llm,context,plugin,simplibs,simplibs-extractor,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: simplibs-extractor>=0.2.0
+Requires-Dist: simplibs-extractor-javascript>=0.1.0
+Requires-Dist: simplibs-extractor-css>=0.1.0
+Requires-Dist: simplibs-text>=0.2.0
+Requires-Dist: simplibs-actions>=0.2.2
+Requires-Dist: simplibs-path>=0.2.0
+Requires-Dist: simplibs-rules>=0.4.0
+Requires-Dist: simplibs-validate>=0.3.2
+Requires-Dist: simplibs-types>=0.2.0
+Requires-Dist: simplibs-exception>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# 🌐 `simplibs-extractor-html`
+
+[![PyPI](https://img.shields.io/pypi/v/simplibs-extractor-html)](https://pypi.org/project/simplibs-extractor-html/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![Licence](https://img.shields.io/badge/licence-MIT-green)](https://github.com/simplibs/simplibs-extractor-html/blob/main/LICENSE)
+[![tests](https://github.com/simplibs/simplibs-extractor-html/actions/workflows/tests.yml/badge.svg)](https://github.com/simplibs/simplibs-extractor-html/actions)
+
+**Pages and templates in one document — Django and Jinja read as the templates they are, the code inside cleaned by the add-on of its own language.**
+
+The HTML add-on of [`simplibs-extractor`](https://pypi.org/project/simplibs-extractor/). The extractor gathers the text files of a folder into one document and knows **no language**; this library teaches it pages and templates: which files are worth reading,
+how to take **comments and imports** out of a source, how to tidy its whitespace without touching a `<pre>`, how to hand the JavaScript in `<script>` and the CSS in `<style>` to the steps of their own add-ons, how to write an **outline** of a page and the **skeleton** of
+a template, and **thirteen ready profiles** that put it together. A page is read by a small scanner that knows tags, quoted values and raw text, never by a regex over the whole page — so a `<!--` inside `title="..."` or inside a script is left alone, and
+a `>` inside `{% if a > b %}` does not end a tag.
+
+```bash
+pip install simplibs-extractor-html
+simplibs-extractor html django-clean my_project
+```
+
+```python
+from simplibs.extractor_html import strip_html_comments, html_outline
+
+strip_html_comments("<p>a</p> <!-- note -->\n<p>b</p>\n")                  # -> '<p>a</p>\n<p>b</p>\n'
+html_outline('<main><h1>Hi</h1><div id="a"></div></main>')                # -> 'main\n  h1 "Hi"\n  div#a\n'
+```
+
+> `pip install` is the whole installation: the library announces itself to the extractor through an entry point, so the profiles show up in `simplibs-extractor --list-profiles html` with nothing to import. It brings the add-ons for JavaScript
+> and CSS with it, because it uses their steps for the code inside a page. The same steps are plain functions (`str -> str`) that you can use without the extractor at all.
+
+---
+
+## 🧭 The Core Philosophy
+
+Cleaning a page with a few regular expressions works until the first file where it does not: a `<!--` inside an attribute, a comment-like string in a script, a `>` inside `{% if a > b %}`, a `<pre>` whose spaces are the content, a `.html` file that is a Jinja
+template whose `{# ... #}` spans three lines. `simplibs-extractor-html` takes those traps seriously:
+
+* **A scanner, not a parser.** One pass that knows tags with their quoted values and the elements whose content is raw text (`script`, `style`, `textarea`, `title`), and jumps from one stop to the next. It builds no tree and it cannot fail: there is no syntax it refuses.
+* **The curly braces first.** In a template `{{ }}`, `{% %}` and `{# #}` are read before the page and blanked out, so the HTML is read from text that has the same length and the same lines. A construct that is not closed is only text; only a block that is opened and never closed is damage.
+* **Django is not Jinja.** A construct stays on one line in Django and may span lines in Jinja; `{% comment %}` and `{% verbatim %}` exist in Django, `{% raw %}` and `{% macro %}` in Jinja. A page cannot say which engine it is written for, so the steps for templates **require the `engine`**,
+  and the profiles come in families: pages, Django, Jinja.
+* **A comment is not always a comment.** A `<!--` inside an attribute or a script is text. An Internet Explorer conditional comment holds real tags and stays by default. With `keep_license=True` the comments that minifiers keep — `<!--! ... -->`, `@license`, `@preserve` — survive.
+* **Whitespace that matters is left alone.** The lines that touch a `<pre>`, a `<textarea>`, a `<script>`, a `<style>` or a verbatim block come out exactly as they went in; everywhere else trailing blanks go and blank runs are reduced.
+* **The code inside a page belongs to its own language.** The step for blocks takes the steps for `<script>` and `<style>` as parameters; the presets give it those of the JavaScript and CSS add-ons. A script that holds JSON or a template of a framework is data, and no step sees it.
+* **A damaged page is left as it is.** A comment, a tag or a `script` that is never closed: the text comes back unchanged, with a warning, and the extractor calls the file `partial`. A step never cuts on a basis it does not trust.
+* **The project's own is its own.** The strict profiles leave out packages of other people and generated output — but `templates/` and `static/` stay, because that is where a Django project keeps its own files, and `public/index.html` of a React project is source.
+* **Functions first, actions on top.** Every step is a plain function; the action is a thin wrapper of the same name, and the presets and profiles are built from the actions. The layers only look left: `constants` ← `annotations` ← `file_rules` ← `logic` ← `actions` ← `presets` ← `profiles` ← `plugin`.
+
+```python
+strip_html_comments("<p>a</p>\n<!-- never closed\n")      # -> '<p>a</p>\n<!-- never closed\n'     unchanged, with a UserWarning: the comment is never closed
+```
+
+---
+
+## 📦 Installation
+
+```bash
+pip install simplibs-extractor-html
+```
+
+Requires Python 3.11+. The package brings [`simplibs-extractor`](https://pypi.org/project/simplibs-extractor/) with it, and the command `simplibs-extractor` is available at once. Runtime dependencies (installed automatically):
+[`simplibs-extractor`](https://pypi.org/project/simplibs-extractor/) (the profile, the registry, `by_suffix`),
+[`simplibs-extractor-javascript`](https://pypi.org/project/simplibs-extractor-javascript/) and [`simplibs-extractor-css`](https://pypi.org/project/simplibs-extractor-css/) (the steps for the code inside `<script>` and `<style>`),
+[`simplibs-text`](https://pypi.org/project/simplibs-text/) (cutting the found ranges, the `Span` type, the whitespace presets),
+[`simplibs-actions`](https://pypi.org/project/simplibs-actions/) (the steps as actions),
+[`simplibs-path`](https://pypi.org/project/simplibs-path/) and [`simplibs-rules`](https://pypi.org/project/simplibs-rules/) (the file rules),
+[`simplibs-validate`](https://pypi.org/project/simplibs-validate/) (`@validate_call` on every public function),
+[`simplibs-types`](https://pypi.org/project/simplibs-types/) (`int_positive`, the depth of the outline) and
+[`simplibs-exception`](https://pypi.org/project/simplibs-exception/) (the `ParamError` of the step for blocks).
+
+---
+
+## 🚀 Quick Start in 60 Seconds
+
+### Level 1: The command line
+
+```bash
+simplibs-extractor html src-clean my_project                       # the project's own pages, cleaned -> my_project/html_src_clean.md
+simplibs-extractor html django-clean my_project                    # Django templates, read as templates -> my_project/html_django_clean.md
+simplibs-extractor html jinja-structure my_project                 # the skeleton of Jinja templates: extends, include, macros, blocks
+simplibs-extractor html outline my_project                         # landmarks, headings and ids — the smallest overview of a page
+simplibs-extractor html django-clean,django-structure my_project   # two profiles -> two files, one run
+simplibs-extractor html data-all my_project --dry-run              # plan and report, write nothing
+simplibs-extractor --list-profiles html                            # the thirteen profiles
+```
+
+Which one? For a **plain site**: `data-all` gives the pages as they are, `code-clean` takes the comments away and cleans the code inside, `src-clean` does the same for the project's own pages only, `code-no-imports` takes also the imports away, and `outline` keeps only
+the map. For a **Django** project use the `django-` profiles, for **Jinja** (or Nunjucks) the `jinja-` ones: `-clean`, `-no-imports`, `-outline`, and `-structure` for the skeleton of the templates.
+
+### Level 2: The steps as functions
+
+```python
+from simplibs.extractor_html import (
+    strip_html_comments, cleanup_html_whitespace, compact_html, html_outline,
+    strip_template_comments, remove_template_imports, template_outline,
+)
+
+strip_html_comments("<p>a</p> <!-- n -->\n<p>b</p>\n")                                          # -> '<p>a</p>\n<p>b</p>\n'
+strip_html_comments("<!--[if IE]><p>ie</p><![endif]-->\n<p>a</p>\n", keep_conditional=False)    # -> '<p>a</p>\n'
+cleanup_html_whitespace("<div>  \n\n\n<p>a</p>   \n</div>\n")                                   # -> '<div>\n\n<p>a</p>\n</div>\n'
+compact_html("<ul>\n\n  <li>a</li>\n\n</ul>\n")                                                 # -> '<ul>\n  <li>a</li>\n</ul>\n'
+html_outline('<ul id="menu"><li id="a">x<li id="b">y</ul>\n')                                   # -> 'ul#menu\n  li#a\n  li#b\n'
+
+strip_template_comments("{# note #}\n<p>a</p>\n", engine="django")                              # -> '<p>a</p>\n'
+remove_template_imports("{% load static %}\n<p>a</p>\n", engine="django")                       # -> '<p>a</p>\n'
+template_outline("{% extends 'b.html' %}{% block a %}{% endblock %}", engine="jinja")           # -> "{% extends 'b.html' %}\n{% block a %}\n"
+```
+
+### Level 3: The code inside a page, actions and ready-made pipelines
+
+```python
+from simplibs.extractor_html import apply_to_html_blocks
+from simplibs.extractor_html.actions import CleanupHtmlWhitespace, StripHtmlComments
+from simplibs.extractor_html.presets import html_clean_steps
+
+apply_to_html_blocks("<style>a{}</style><script>b</script>", style=str.upper)     # -> '<style>A{}</style><script>b</script>'      any `str -> str` is a step
+
+steps = StripHtmlComments() >> CleanupHtmlWhitespace()
+steps("<!-- n -->\n\n\n<p>a</p>  \n")                                              # -> '<p>a</p>\n'
+
+html_clean_steps("django")("{# n #}\n<!-- c -->\n<p>{{ a }}</p>\n\n\n")             # -> '<p>{{ a }}</p>\n'
+```
+
+### Level 4: Your own profile from the parts
+
+File rules combine with `&`, `|` and `~`; the steps are presets; a registered profile is a name for both.
+
+```python
+from simplibs.extractor import Profile, by_suffix, extract, register_profile
+from simplibs.extractor_html.constants import HTML_PLAIN_SUFFIXES
+from simplibs.extractor_html.file_rules import HTML_PLAIN_BASE, OUTPUT_DIRS
+from simplibs.extractor_html.presets import html_clean_steps
+
+register_profile(Profile(
+    system="html", name="own-django",
+    description="Django templates, generated pages left out, comments out",
+    include=HTML_PLAIN_BASE,
+    exclude=OUTPUT_DIRS,
+    steps=by_suffix(html_clean_steps("django"), HTML_PLAIN_SUFFIXES),
+    output_name="html_own_django.md",
+))
+
+extract(source="my_project", profile="html/own-django")
+```
+
+A changed copy of a profile of this library is one `dataclasses.replace` away:
+
+```python
+from dataclasses import replace
+from simplibs.extractor_html.profiles import DJANGO_CLEAN
+
+mine = replace(DJANGO_CLEAN, name="mine", output_name="mine.md")
+```
+
+---
+
+## 🛠️ Architecture & Package Structure
+
+```
+src/simplibs/extractor_html/
+├── constants/            ◄── Suffixes, folder names, licence marks, tables of names, the patterns of the two scanners
+├── annotations/          ◄── TemplateEngine: "django" or "jinja"
+├── file_rules/           ◄── Rules on the path inside the source (domain folder)
+│   ├── atomic/           ◄── DOT_NAME, VCS_DIRS, DEPENDENCY_DIRS, OUTPUT_DIRS, WRAPPED_HTML
+│   └── html/             ◄── HTML_FILES, HTML_BASE, HTML_PLAIN_BASE, HTML_STRICT_EXCLUDE
+├── logic/                ◄── The steps for pages: comments, whitespace, the code inside, the outline
+│   ├── templates/        ◄── The steps for Django and Jinja templates: comments, imports, the skeleton
+│   └── _helpers/         ◄── Private: the two scanners (scan_html, scan_templates) and the small parts they are made of
+├── actions/              ◄── The steps as Action classes (domain folder)
+├── presets/              ◄── Ready-made pipelines, functions of the engine (domain folder)
+├── profiles/             ◄── The thirteen Profile objects and HTML_PROFILES (domain folder)
+├── plugin/               ◄── register_all: the target of the entry point
+└── py.typed
+```
+
+The folder `_helpers/` is private: it holds the scanners and the parts they are made of, and nothing in it is a public name.
+
+The package root exports **the steps**, `TemplateEngine` and `register_all`. The four domain folders have their own `__all__` and are imported through their domain — a function and an action are different kinds of thing and should stay visibly different at the import line:
+
+```python
+from simplibs.extractor_html import strip_html_comments, html_outline, TemplateEngine, register_all    # the steps, the type, the entry point
+from simplibs.extractor_html.actions import StripHtmlComments                                       # the steps as actions
+from simplibs.extractor_html.file_rules import HTML_BASE, HTML_STRICT_EXCLUDE                       # the rules
+from simplibs.extractor_html.presets import html_clean_steps                                        # ready-made pipelines
+from simplibs.extractor_html.profiles import DJANGO_CLEAN                                           # the profiles as objects
+```
+
+The fixed values are imported from `simplibs.extractor_html.constants`. The ranges the steps find are `simplibs.text.Span`; the type is taken from `simplibs-text`, not defined here. The steps themselves know nothing of the JavaScript and CSS add-ons: only the presets use them.
+
+---
+
+## 🔧 `logic/` — The steps that read pages
+
+Plain functions: a page as a text in, a text out (one of them gives the positions of the comments). All take their options as keyword-only parameters, and `engine=None` for a page that is only HTML. A page that looks damaged comes back unchanged, with a warning.
+
+| Function                  | Description / Parameters                                                                                                                                                              |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `html_comment_spans`      | Finds the HTML comments; returns a `Span` for each, from the blanks in front to the end (`text`, keyword-only: `engine=None`, `keep_conditional=True`, `keep_license=False`).          |
+| `strip_html_comments`     | Removes the HTML comments; a line that held only a comment disappears (`text`, keyword-only: `engine=None`, `keep_conditional=True`, `keep_license=False`).                              |
+| `cleanup_html_whitespace` | Trims line ends, reduces blank runs to one; spares `pre`, `textarea`, `script`, `style` and verbatim blocks (`text`, keyword-only: `engine=None`).                                    |
+| `compact_html`            | Drops every blank line; spares the same places (`text`, keyword-only: `engine=None`).                                                                                                 |
+| `apply_to_html_blocks`    | Runs the steps you give on the code inside `script` and `style` (`text`, keyword-only: `script=None`, `style=None`, `engine=None`).                                                    |
+| `html_outline`            | Writes the landmarks, the headings and every element with an `id`, indented by nesting (`text`, keyword-only: `engine=None`, `max_depth=None`).                                         |
+
+➡️ [README_EXTRACTOR_HTML_LOGIC](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/logic/README_EXTRACTOR_HTML_LOGIC.md)
+
+---
+
+## 🧾 `logic/templates/` — The steps for Django and Jinja templates
+
+Plain functions that read only `{{ }}`, `{% %}` and `{# #}`; the HTML around them is not read. The **`engine` is required** (`"django"` or `"jinja"`): a page cannot say which one it is written for.
+
+| Function                  | Description / Parameters                                                                                                                         |
+|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `template_comment_spans`  | Finds `{# ... #}` and `{% comment %}`; returns a `Span` for each (`text`, keyword-only: `engine`).                                              |
+| `strip_template_comments` | Removes `{# ... #}` and `{% comment %} ... {% endcomment %}` (`text`, keyword-only: `engine`).                                                   |
+| `remove_template_imports` | Removes `{% load %}` (Django), `{% import %}` and `{% from %}` (Jinja); `extends` and `include` stay (`text`, keyword-only: `engine`).          |
+| `template_outline`        | Writes the skeleton: `extends`, `include`, the blocks, and in Jinja the macros (`text`, keyword-only: `engine`, `max_depth=None`).              |
+
+➡️ [README_EXTRACTOR_HTML_TEMPLATES](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/logic/README_EXTRACTOR_HTML_TEMPLATES.md)
+
+---
+
+## 🏷️ `annotations/` — Types for the signatures
+
+| Type             | Description                                                                                  |
+|------------------|----------------------------------------------------------------------------------------------|
+| `TemplateEngine` | `Literal["django", "jinja"]` — the template language of a page (Nunjucks counts as Jinja).  |
+
+➡️ [README_EXTRACTOR_HTML_ANNOTATIONS](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_ANNOTATIONS.md)
+
+---
+
+## ⚙️ `actions/` — Pipeline steps
+
+Every step except the two `*_comment_spans` is also an `Action` of [`simplibs-actions`](https://pypi.org/project/simplibs-actions/): configured once, called with the **text** as its main input, chainable with `>>`. The options of the function are the options of the action:
+`StripHtmlComments(engine="django")`. Actions are a separate domain, imported through `simplibs.extractor_html.actions`.
+
+| Action                  | Over                      | Description                                                      |
+|-------------------------|---------------------------|------------------------------------------------------------------|
+| `StripHtmlComments`     | `strip_html_comments`     | Takes the HTML comments out of the page flowing in.              |
+| `StripTemplateComments` | `strip_template_comments` | Takes the template comments out (`engine` required).             |
+| `RemoveTemplateImports` | `remove_template_imports` | Takes `{% load %}`, `{% import %}` and `{% from %}` out (`engine` required). |
+| `CleanupHtmlWhitespace` | `cleanup_html_whitespace` | Tidies the whitespace, sparing `pre` and the like.               |
+| `CompactHtml`           | `compact_html`            | Drops every blank line, sparing `pre` and the like.              |
+| `ApplyToHtmlBlocks`     | `apply_to_html_blocks`    | Runs the given steps on the code inside `script` and `style`.    |
+| `HtmlOutline`           | `html_outline`            | Turns the page into the list of its landmarks, headings and ids. |
+| `TemplateOutline`       | `template_outline`        | Turns the template into the list of its `extends`, `include` and blocks (`engine` required). |
+
+➡️ [README_EXTRACTOR_HTML_ACTIONS](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_ACTIONS.md)
+
+---
+
+## 🧩 `presets/` — Ready-made pipelines
+
+The chains of actions that the profiles use. Each is a **function of the engine** (`None` for a page that is only HTML), because the chain is the same for every engine and only the option of its actions differs. The code inside a page is cleaned by `JS_CLEAN` and
+`CSS_PLAIN_CLEAN` of the other add-ons.
+
+| Preset                     | Description / Parameters                                                                                                                       |
+|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| `html_clean_steps`         | Comments out, the code inside cleaned, whitespace tidied; imports stay (`engine`).                                                              |
+| `html_no_imports_steps`    | The same, without imports and without blank lines (`engine`).                                                                                    |
+| `html_outline_steps`       | The landmarks, headings and ids of a page (`engine`).                                                                                            |
+| `template_structure_steps` | The `extends`, `include` and blocks of a template (`engine`, never `None`).                                                                      |
+
+➡️ [README_EXTRACTOR_HTML_PRESETS](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_PRESETS.md)
+
+---
+
+## 📋 `profiles/` — The thirteen profiles
+
+Registered in the system `html`; also importable as `Profile` objects. Three families: **pages** (every `.html` is read without an engine; a Jinja suffix as Jinja), **Django** and **Jinja** (every file read with that engine, strict).
+
+| Profile                  | Output                      | Description                                                                                          |
+|--------------------------|-----------------------------|------------------------------------------------------------------------------------------------------|
+| `html/code-clean`        | `html_code_clean.md`        | Pages without comments and extra blank lines, the code inside cleaned too (imports stay).             |
+| `html/code-no-imports`   | `html_code_no_imports.md`   | Pure content: no comments, imports (also inside script and style) or blank lines.                     |
+| `html/data-all`          | `html_data_all.md`          | Every relevant page, as it is.                                                                       |
+| `html/outline`           | `html_outline.md`           | Overview of the pages: landmarks, headings and every element with an id.                             |
+| `html/src-clean`         | `html_src_clean.md`         | Like `code-clean`, without packages of other people and generated pages.                              |
+| `html/django-clean`      | `html_django_clean.md`      | Django templates without HTML and template comments and extra blank lines (imports stay).            |
+| `html/django-no-imports` | `html_django_no_imports.md` | Django templates reduced to their content: no comments, `{% load %}`, imports in script and style, or blank lines. |
+| `html/django-outline`    | `html_django_outline.md`    | Overview of Django templates as pages: landmarks, headings and every element with an id.             |
+| `html/django-structure`  | `html_django_structure.md`  | Skeleton of Django templates: extends, include and blocks.                                           |
+| `html/jinja-clean`       | `html_jinja_clean.md`       | Jinja templates without HTML and template comments and extra blank lines (imports stay).             |
+| `html/jinja-no-imports`  | `html_jinja_no_imports.md`  | Jinja templates reduced to their content: no comments, `{% import %}` and `{% from %}`, imports in script and style, or blank lines. |
+| `html/jinja-outline`     | `html_jinja_outline.md`     | Overview of Jinja templates as pages: landmarks, headings and every element with an id.              |
+| `html/jinja-structure`   | `html_jinja_structure.md`   | Skeleton of Jinja templates: extends, include, macros and blocks.                                    |
+
+`HTML_PROFILES` is the tuple of all thirteen, in the order the listings show them.
+
+➡️ [README_EXTRACTOR_HTML_PROFILES](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_PROFILES.md)
+
+---
+
+## 📐 `file_rules/` — Which files are worth reading
+
+Rules on the path **inside** the source folder: `Rule` objects of [`simplibs-rules`](https://pypi.org/project/simplibs-rules/), composable with `&`, `|` and `~`.
+
+| Rule                  | Description                                                                                                         |
+|-----------------------|---------------------------------------------------------------------------------------------------------------------|
+| `HTML_BASE`           | The default choice: every page and template that is not hidden — Jinja suffixes and `.html.j2` included.             |
+| `HTML_PLAIN_BASE`     | The pages with a `.html`, `.htm` or `.xhtml` suffix, not hidden: the files a Django project keeps its templates in.  |
+| `HTML_FILES`          | A file with a page or template suffix, or a wrapped page (`index.html.j2`).                                          |
+| `HTML_STRICT_EXCLUDE` | What is not the project's own source: packages of other people, generated output, version control.                   |
+| `DOT_NAME`            | The file name starts with a dot.                                                                                    |
+| `VCS_DIRS`            | A folder above the file is a version-control folder (`.git`, `.svn`, `.hg`, `.bzr`).                                 |
+| `DEPENDENCY_DIRS`     | A folder above the file holds pages of other people (`node_modules`, `bower_components`, `vendor`).                  |
+| `OUTPUT_DIRS`         | A folder above the file holds generated pages (`dist`, `_build`, `_site`, `staticfiles`, `htmlcov`, …).              |
+| `WRAPPED_HTML`        | The file is a page behind a wrapper suffix: `index.html.j2`, not `nginx.conf.j2`.                                   |
+
+➡️ [README_EXTRACTOR_HTML_FILE_RULES](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_FILE_RULES.md)
+
+---
+
+## 🔖 `constants/` — Fixed values
+
+Thirty fixed values the rules, the scanners, the steps and the profiles are built from.
+
+| Constant                         | Description                                                                          |
+|----------------------------------|--------------------------------------------------------------------------------------|
+| `HTML_PLAIN_SUFFIXES`            | `(".html", ".htm", ".xhtml")` — pages, and Django templates with them.               |
+| `HTML_TEMPLATE_SUFFIXES`         | `(".jinja", ".jinja2", ".njk")` — templates of the Jinja family.                     |
+| `HTML_WRAPPED_SUFFIXES`          | `(".j2",)` — the wrapper around the real suffix.                                     |
+| `HTML_SUFFIXES`                  | The three above joined: every suffix the library may read.                           |
+| `HTML_WRAPPED_STEM_ENDING`       | `".html"` — what the stem of a wrapped page ends with.                               |
+| `HTML_EXTRA_LANGUAGE_BY_SUFFIX`  | The code-fence language of the suffixes the extractor does not know.                 |
+| `HTML_DEPENDENCY_DIR_NAMES`      | Folders of pages written by other people.                                            |
+| `HTML_OUTPUT_DIR_NAMES`          | Folders of generated pages and reports.                                              |
+| `HTML_LICENSE_START`             | `"<!--!"` — how a comment that has to survive minification begins.                   |
+| `HTML_LICENSE_TAGS`              | `("@license", "@preserve")` — words that mark a comment as one to keep.              |
+| `HTML_OUTLINE_ELEMENTS`          | The landmarks and other big parts that always appear in the outline.                 |
+| `HTML_HEADING_ELEMENTS`          | The six headings.                                                                    |
+| `HTML_TEXT_ELEMENTS`             | The title and the headings: listed with their text.                                  |
+| `HTML_OUTLINE_TEXT_LIMIT`        | `80` — the longest heading text in the outline.                                      |
+| `HTML_VOID_ELEMENTS`             | The elements that have no content and no end tag.                                    |
+| `HTML_IMPLIED_END`               | Which start tags close which open elements (`<li>a<li>b`).                           |
+| `HTML_BLOCK_LANGUAGE_BY_TYPE`    | Which `type` values make a `script` or `style` code, and of what language.           |
+| `HTML_TEMPLATE_BLOCKS`           | The template tags that swallow everything up to an end tag.                          |
+| `HTML_TEMPLATE_IMPORT_TAGS`      | The template tags that bring in names from elsewhere.                                |
+| `HTML_TEMPLATE_OUTLINE_TAGS`     | The template tags of the skeleton: open, close, standalone.                          |
+| `HTML_TOKEN_PATTERN`             | Where markup begins in a page.                                                       |
+| `HTML_COMMENT_END_PATTERN`       | `-->` and `--!>`.                                                                    |
+| `HTML_CONDITIONAL_PATTERN`       | The beginning of an Internet Explorer conditional comment.                           |
+| `HTML_TAG_NAME_PATTERN`          | The name of a tag.                                                                   |
+| `HTML_ID_ATTRIBUTE_PATTERN`      | The `id` attribute of a tag.                                                         |
+| `HTML_TYPE_ATTRIBUTE_PATTERN`    | The `type` attribute of a tag.                                                       |
+| `HTML_ANY_TAG_PATTERN`           | Anything that looks like a tag (to take the markup out of a heading).                |
+| `HTML_RAW_TEXT_END_PATTERNS`     | The end tag of each element with raw text: `script`, `style`, `textarea`, `title`.   |
+| `HTML_TEMPLATE_TOKEN_PATTERN`    | Where a template construct begins: `{#`, `{%`, `{{`.                                 |
+| `HTML_TEMPLATE_TAG_NAME_PATTERN` | The name of a template tag.                                                          |
+
+➡️ [README_EXTRACTOR_HTML_CONSTANTS](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_CONSTANTS.md)
+
+---
+
+## 🔌 `plugin/` — The meeting point with the extractor
+
+| Function       | Description / Parameters                                                                                                                                                                         |
+|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `register_all` | Registers the languages of `.htm`, `.xhtml` and the Jinja suffixes and the thirteen profiles in the extractor's registries and returns the profile keys; the target of the entry point `simplibs.extractor.plugins` (keyword-only: `replace_existing=True`). |
+
+The entry point lives in this library's `pyproject.toml`; the extractor's `load_plugins()` finds it, so nothing is imported by name. From Python, call `load_plugins()` of the extractor once before a profile is looked up.
+
+➡️ [README_EXTRACTOR_HTML_PLUGIN](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_PLUGIN.md)
+
+---
+
+## ⚠️ Exceptions
+
+**A page is never the cause of an error**: a file that looks damaged is a warning, not an exception. The library raises **one card of its own**, as a structured [`simplibs.exception`](https://pypi.org/project/simplibs-exception/) error; a caller that wants "any error of the
+family" catches `SimpleError`.
+
+| Exception    | Raised by              | Raised when                                                                        |
+|--------------|------------------------|------------------------------------------------------------------------------------|
+| `ParamError` | `apply_to_html_blocks` | A step for a `script` or `style` block returns something that is not a `str`.      |
+
+What is an exception and what is not:
+
+| Situation                                                                                   | How it is reported                                                              |
+|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| A step called directly on a page with a comment, a tag, a `script` or a template block never closed | a `UserWarning`; the text comes back unchanged (the `*_comment_spans`: `[]`) |
+| `template_outline` on a template whose blocks do not pair up                                | a `UserWarning`; the text comes back unchanged                                  |
+| The same inside an **extraction**                                                           | **not raised**: the file stays in the output, marked `partial`, the warning is in the report |
+| A construct that is not closed (`{{` without `}}`)                                          | **nothing**: it is only text                                                    |
+| A wrong **type or value** of an argument (`text=5`, `max_depth=0`, `engine="jinja2"`)      | a `ValidationError` from `simplibs-validate`                                    |
+| A step of your own that raises inside `apply_to_html_blocks`                                | its exception, as it was                                                        |
+| A profile key that is taken, with `register_all(replace_existing=False)`                    | the card of the extractor's registry (`EXTRACTOR_PROFILE_EXISTS`)               |
+
+Each helper README ends with the errors of its own package.
+
+---
+
+## 📚 Documentation
+
+The detailed references — every function, rule and profile with its parameters, return value, raised errors, an example and a look under the hood:
+
+| Reference | What it describes |
+|-----------|-------------------|
+| [LOGIC](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/logic/README_EXTRACTOR_HTML_LOGIC.md) | the six steps for pages: comments, whitespace, the code inside, the outline — and the scanner under them |
+| [TEMPLATES](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/logic/README_EXTRACTOR_HTML_TEMPLATES.md) | the four steps for Django and Jinja templates — and the scanner of the curly braces |
+| [ANNOTATIONS](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_ANNOTATIONS.md) | `TemplateEngine` |
+| [ACTIONS](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_ACTIONS.md) | the steps as pipeline actions |
+| [PRESETS](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_PRESETS.md) | the four ready-made pipelines, functions of the engine |
+| [PROFILES](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_PROFILES.md) | the thirteen profiles in three families, one page through each, a profile of your own |
+| [FILE_RULES](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_FILE_RULES.md) | which files are worth reading: the atomic pieces and the rules of a page project |
+| [CONSTANTS](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_CONSTANTS.md) | the fixed values: suffixes, folder names, tables of names, the patterns of the scanners |
+| [PLUGIN](https://github.com/simplibs/simplibs-extractor-html/blob/main/docs/README_EXTRACTOR_HTML_PLUGIN.md) | `register_all` and how the extractor finds this add-on |
+
+---
+
+## 🔗 Related libraries
+
+* **[`simplibs-extractor`](https://pypi.org/project/simplibs-extractor/)** — the extractor this library is an add-on of: the six phases, the profiles and the command.
+* **[`simplibs-extractor-javascript`](https://pypi.org/project/simplibs-extractor-javascript/)** and **[`simplibs-extractor-css`](https://pypi.org/project/simplibs-extractor-css/)** — the add-ons whose steps clean the code inside `<script>` and `<style>`; `JS_CLEAN`, `JS_NO_IMPORTS`, `CSS_PLAIN_CLEAN` and `CSS_PLAIN_NO_IMPORTS` are used by the presets.
+* **[`simplibs-extractor-python`](https://pypi.org/project/simplibs-extractor-python/)** — the sister add-on for Python projects (a Django project often has both).
+* **[`simplibs-text`](https://pypi.org/project/simplibs-text/)** — `remove_spans` cuts the ranges the steps find, `Span` is their type; `CLEANUP_WHITESPACE` and `COMPACT` are the whitespace presets the code inside a page is closed with.
+* **[`simplibs-actions`](https://pypi.org/project/simplibs-actions/)** — the `Action` the steps are wrapped in.
+* **[`simplibs-path`](https://pypi.org/project/simplibs-path/)** — the path rules (`HasSuffix`, `NameIs`, `StemIs`, `AnyParentNameIs`) and `IGNORE_VCS`.
+* **[`simplibs-rules`](https://pypi.org/project/simplibs-rules/)** — the `Rule` object and its building blocks (`IsIn`, `StartsWith`, `EndsWith`).
+* **[`simplibs-validate`](https://pypi.org/project/simplibs-validate/)** and **[`simplibs-types`](https://pypi.org/project/simplibs-types/)** — the check of every signature, and the `int_positive` type of the outline depth.
+* **[`simplibs-exception`](https://pypi.org/project/simplibs-exception/)** — the structured error cards; `ParamError` of the step for blocks comes from it.
+
+---
+
+## ☯️ About simplibs
+
+All libraries in the **simplibs** (Simple Libraries) ecosystem share a common
+engineering philosophy:
+
+* **Dyslexia-friendly:**
+We actively minimize cognitive load. Code is atomized into small, self-contained units,
+files are named directly after the logical task they perform, and explanations describe
+*why* something is designed, not just *what* it is.
+* **Programmer's Zen:**
+Nothing should be missing, and nothing should be superfluous. We value clean execution
+paths and robust, understandable code architectures over rushed, messy feature sets.
+* **Defensive Style:**
+We actively anticipate edge cases and failure modes so that only safe operational paths
+remain. Our code is built to degrade gracefully rather than crash unexpectedly.
+* **Minimalism:**
+Find the most direct path to the goal in as few operational steps as possible without
+taking shortcuts on safety, readability, or completeness.
+* **Code as Craft:**
+Code should be pleasant to look at, readable at a glance, and evoke structural harmony.
+We treat software engineering as a precision trade.
+
+---
+
+### 🤝 Contributing & Community
+
+This is an **open-source project** built with love and care. We strongly believe in
+community collaboration and welcome any feedback, bug reports, or feature ideas!
+
+* **Want to contribute?** Feel free to open an Issue or submit a Pull Request.
+* **Want to get in touch?** If you'd like to discuss the project further, collaborate,
+  or just say hello, feel free to open a GitHub Issue or start a Discussion.
+
+---
+
+### 📝 License
+
+This library is released under the **MIT License**. Build great things!
+
+---