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!

---
