### Setup Text-Forge Development Environment

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Clone the Text-Forge repository and install dependencies using make. Ensure you have Git installed.

```bash
git clone https://github.com/shared-goals/text-forge.git
cd text-forge
make install  # uv sync
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Installs project dependencies using uv. Ensure uv is in your environment.

```bash
make install
```

--------------------------------

### Serve MkDocs Site Locally

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Starts a fast preview server for the MkDocs site. Does not require pandoc.

```bash
cd whattodo && make serve
```

--------------------------------

### Build EPUB Output

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Builds the EPUB version of the book. Requires pandoc to be installed.

```bash
cd whattodo && make epub
```

--------------------------------

### Install text-forge Python Package

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Install the text-forge package using pip.

```bash
pip install sg-text-forge
```

--------------------------------

### text-forge info CLI

Source: https://context7.com/shared-goals/text-forge/llms.txt

Displays the text-forge version and environment details, including Python version and installation path. Useful for debugging and verifying installation.

```bash
text-forge info
# text-forge version: 0.1.14
# Python: 3.12.0 (main, ...)
# Installed from: /usr/local/lib/python3.12/site-packages/text_forge
```

--------------------------------

### text-forge info

Source: https://context7.com/shared-goals/text-forge/llms.txt

Displays the installed `text-forge` version and environment information using the `text-forge` CLI.

```APIDOC
## text-forge info

### Description
Show version and environment information.

### Usage
```bash
text-forge info
```

### Output Example
```
text-forge version: 0.1.14
Python: 3.12.0 (main, ...)
Installed from: /usr/local/lib/python3.12/site-packages/text_forge
```
```

--------------------------------

### Live Save Endpoint for Browser Editor

Source: https://context7.com/shared-goals/text-forge/llms.txt

This bash script demonstrates how to send a POST request to the live save endpoint (`/_text_forge/save`) during `mkdocs serve`. It shows the expected request format and example success/error responses.

```bash
# Request format sent by editor.js during local development:
curl -X POST http://localhost:8000/_text_forge/save \
  -H "Content-Type: application/json" \
  -d '{
    "filePath": "chapter1.md",
    "content": "# Chapter 1\n\nUpdated content here."
  }'

# Success response:
# {"success": true, "path": "/absolute/path/to/docs/chapter1.md"}

# Error responses:
# 400: {"error": "Missing filePath or content"}
# 403: {"error": "Invalid file path"}   ← path traversal attempt blocked
# 500: {"error": "<exception message>"}

```

--------------------------------

### Install Obsidian Plugin with text-forge CLI

Source: https://context7.com/shared-goals/text-forge/llms.txt

Installs the text-forge Obsidian plugin, Templater scripts, templates, and hotkeys into an Obsidian vault. Skips user-customizable files if they exist, but always overwrites the plugin itself.

```bash
# Install into current directory (vault root)
text-forge obsidian install

# Install into a specific vault
text-forge obsidian install --vault /path/to/my-vault

# Files installed:
#   .obsidian/plugins/text-forge/main.js
#   .obsidian/plugins/text-forge/manifest.json
#   .obsidian/community-plugins.json        ← "text-forge" entry added
#   .obsidian/plugins/templater-obsidian/data.json  (skip if exists)
#   obsidian/scripts/insert_block.js        (skip if exists)
#   obsidian/scripts/insert_image.js        (skip if exists)
#   obsidian/scripts/insert_link.js         (skip if exists)
#   obsidian/templates/insert_block.md      (skip if exists)
```

--------------------------------

### Configure Text-Forge MkDocs Plugin

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Example configuration for the Text-Forge plugin in MkDocs. Customize editor, download options, EPUB metadata, and UI labels.

```yaml
plugins:
  - text-forge:
      # Editor
      editor_enabled: true                    # Show editor widget
      nobr_emoticons_enabled: true            # Wrap emoticons in md-nobr
      
      # Downloads
      downloads_enabled: false                # Show EPUB download button
      ai_readable_enabled: false              # Show "Open in Perplexity" button
      
      # EPUB Metadata (overrides site_name, site_author, etc.)
      epub_title: ""                          # Book title
      epub_subtitle: ""                       # Book subtitle
      epub_author: ""                         # Author name
      epub_identifier: ""                     # ISBN or URL
      epub_publisher: ""                      # Publisher name
      epub_rights: ""                         # Copyright notice
      
      # UI Labels
      source_file_published_title: "Published"  # Source link label
      
      # Theme
      auto_configure_theme: true              # Auto-set theme overrides

```

--------------------------------

### Lint Code with Ruff

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Runs ruff checks for code quality and style. Ensure ruff is installed.

```bash
make lint
```

--------------------------------

### text-forge obsidian install

Source: https://context7.com/shared-goals/text-forge/llms.txt

Installs the `text-forge` Obsidian plugin, Templater scripts, templates, and hotkeys into an Obsidian vault using the `text-forge` CLI.

```APIDOC
## text-forge obsidian install

### Description
Installs the bundled text-forge Obsidian plugin, Templater scripts, templates, and hotkeys into an Obsidian vault. Skips user-customizable files if they already exist; always overwrites the plugin itself to ensure the latest version.

### Usage
```bash
# Install into the current directory (vault root)
text-forge obsidian install

# Install into a specific vault
text-forge obsidian install --vault /path/to/my-vault
```

### Files Installed
- `.obsidian/plugins/text-forge/main.js`
- `.obsidian/plugins/text-forge/manifest.json`
- `.obsidian/community-plugins.json` (adds `"text-forge"` entry)
- `.obsidian/plugins/templater-obsidian/data.json` (skipped if exists)
- `obsidian/scripts/insert_block.js` (skipped if exists)
- `obsidian/scripts/insert_image.js` (skipped if exists)
- `obsidian/scripts/insert_link.js` (skipped if exists)
- `obsidian/templates/insert_block.md` (skipped if exists)
```

--------------------------------

### Format and Lint Code

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Formats code using ruff for import sorting and general formatting. Ensure ruff is installed.

```bash
make format
```

--------------------------------

### Build Complete Site with text-forge

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Build both the EPUB and the complete static site using the text-forge CLI.

```bash
text-forge build --config=mkdocs.yml --build-dir=build
```

--------------------------------

### Perform Full Build (EPUB + Site)

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Executes a full build process, generating both the EPUB and the MkDocs site.

```bash
cd whattodo && make all
```

--------------------------------

### Complete Site + EPUB Build Pipeline

Source: https://context7.com/shared-goals/text-forge/llms.txt

Runs the full pipeline: EPUB generation, then `mkdocs build`, then optionally copies artifacts to the site root and creates a `404.html` legacy-URL redirect.

```python
from pathlib import Path
from text_forge.build import build_site_pipeline

build_site_pipeline(
    config_path=Path("mkdocs.yml"),
    build_dir=Path("build"),
    site_dir=Path("public"),        # None = read from mkdocs.yml
    strict=True,                    # fail on MkDocs warnings
    copy_artifacts=True,            # copy EPUB + combined.md to site root
    create_404_redirect=True,       # create 404.html that redirects /ru/* → /*
)
# Final layout:
#   public/               ← MkDocs HTML site
#   public/my_book.epub   ← EPUB downloadable from site
#   public/combined.md    ← combined Markdown downloadable from site
#   public/404.html       ← legacy-URL redirect handler
```

--------------------------------

### build_site_pipeline

Source: https://context7.com/shared-goals/text-forge/llms.txt

Runs the complete pipeline for building a static site and an EPUB. It first generates the EPUB, then runs `mkdocs build`, and optionally copies artifacts to the site root and creates a `404.html` redirect.

```APIDOC
## build_site_pipeline — Complete site + EPUB build

### Description
Runs the full pipeline: EPUB generation, then `mkdocs build`, then optionally copies artifacts to the site root and creates a `404.html` legacy-URL redirect.

### Method
```python
from pathlib import Path
from text_forge.build import build_site_pipeline

build_site_pipeline(
    config_path=Path("mkdocs.yml"),
    build_dir=Path("build"),
    site_dir=Path("public"),        # None = read from mkdocs.yml
    strict=True,                    # fail on MkDocs warnings
    copy_artifacts=True,            # copy EPUB + combined.md to site root
    create_404_redirect=True,       # create 404.html that redirects /ru/* → /*
)
# Final layout:
#   public/               ← MkDocs HTML site
#   public/my_book.epub   ← EPUB downloadable from site
#   public/combined.md    ← combined Markdown downloadable from site
#   public/404.html       ← legacy-URL redirect handler
```
```

--------------------------------

### text-forge build CLI

Source: https://context7.com/shared-goals/text-forge/llms.txt

Performs a full build including EPUB, MkDocs site, artifact copying, and 404 redirect. Options to skip artifact copy, redirect creation, or run in non-strict mode are available.

```bash
# Full build: EPUB + MkDocs site + artifact copy + 404 redirect
text-forge build \
  --config mkdocs.yml \
  --build-dir build \
  --site-dir public \
  --strict \
  --copy-artifacts \
  --create-404-redirect

# Skip artifact copy and redirect (CI environments that handle this separately)
text-forge build \
  --config mkdocs.yml \
  --no-copy-artifacts \
  --no-create-404-redirect

# Non-strict (don't fail on MkDocs warnings)
text-forge build --no-strict
```

--------------------------------

### Run All Tests

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Executes the full test suite for the project from the root directory.

```bash
make test
```

--------------------------------

### text-forge build CLI Command

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Command to build the complete site, including EPUB and MkDocs output. Options control configuration, build directory, site output, strictness, and artifact copying.

```bash
text-forge build [OPTIONS]

Options:
  --config PATH              Path to mkdocs.yml (default: mkdocs.yml)
  --build-dir PATH           Build directory (default: build)
  --site-dir PATH            MkDocs output (default: from mkdocs.yml)
  --strict/--no-strict       Fail on warnings (default: true)
  --copy-artifacts/--no-copy-artifacts
                             Copy EPUB to site root (default: true)
  --create-404-redirect/--no-create-404-redirect
                             Create 404.html for /ru/* redirects (default: true)
```

--------------------------------

### Copy Build Artifacts to Site Root

Source: https://context7.com/shared-goals/text-forge/llms.txt

Copies generated EPUB and combined Markdown files from the build directory to the MkDocs site root for availability on the published site. Ensure the build and site directories exist.

```python
from pathlib import Path
from text_forge.build import copy_build_artifacts

copy_build_artifacts(
    build_dir=Path("build"),
    site_dir=Path("public"),
    epub_filename="text_book.epub",
    combined_filename="text_combined.md",
)
```

--------------------------------

### Build EPUB with text-forge

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Generate an EPUB file from your MkDocs project using the text-forge CLI.

```bash
text-forge epub --config=mkdocs.yml --build-dir=build
```

--------------------------------

### Full EPUB Build Pipeline

Source: https://context7.com/shared-goals/text-forge/llms.txt

Orchestrates the four-step pipeline for EPUB generation: combine chapters, normalize syntax, process metadata, and generate EPUB via pandoc. Returns the Path to the generated .epub file.

```python
from pathlib import Path
from text_forge.build import build_epub_pipeline

epub_path = build_epub_pipeline(
    config_path=Path("mkdocs.yml"),
    build_dir=Path("build"),
    epub_filename="my_book.epub",       # default: "text_book.epub"
    combined_filename="combined.md",    # default: "text_combined.md"
)
# Outputs:
#   build/combined.md      — all chapters merged into one Markdown file
#   build/pandoc.md        — PyMdown syntax normalized for Pandoc
#   build/book_meta.yml    — EPUB metadata (title, author, edition, date)
#   build/my_book.epub     — final EPUB3 file
print(f"EPUB ready: {epub_path}")
```

--------------------------------

### Load MkDocs Configuration

Source: https://context7.com/shared-goals/text-forge/llms.txt

Loads a MkDocs YAML configuration file, handling custom tags like !ENV. Access site settings and plugin configurations directly from the returned dictionary.

```python
from pathlib import Path
from text_forge.build import load_mkdocs_config

config = load_mkdocs_config(Path("mkdocs.yml"))

print(config["site_name"])
print(config["docs_dir"])
print(config["site_url"])

# Access plugin settings:
for plugin in config.get("plugins", []):
    if isinstance(plugin, dict) and "text-forge" in plugin:
        tf_config = plugin["text-forge"]
        print(tf_config.get("epub_title"))
```

--------------------------------

### text-forge build

Source: https://context7.com/shared-goals/text-forge/llms.txt

Performs a full build process including EPUB generation, MkDocs site build, artifact copying, and 404 redirect creation via the `text-forge` CLI.

```APIDOC
## text-forge build

### Description
Builds site + EPUB. Performs a full build: EPUB, MkDocs site, artifact copy, and 404 redirect.

### Usage
```bash
# Full build with artifacts and redirect
text-forge build \
  --config mkdocs.yml \
  --build-dir build \
  --site-dir public \
  --strict \
  --copy-artifacts \
  --create-404-redirect

# Build skipping artifact copy and redirect
text-forge build \
  --config mkdocs.yml \
  --no-copy-artifacts \
  --no-create-404-redirect

# Non-strict build (ignores MkDocs warnings)
text-forge build --no-strict
```

### Options
- `--config <path>`: Path to the `mkdocs.yml` file.
- `--build-dir <path>`: Directory for build artifacts.
- `--site-dir <path>`: MkDocs site root directory.
- `--strict`: Fail build on MkDocs warnings (default).
- `--no-strict`: Do not fail build on MkDocs warnings.
- `--copy-artifacts`: Copy build artifacts to the site directory.
- `--no-copy-artifacts`: Skip copying build artifacts.
- `--create-404-redirect`: Create a legacy URL redirect `404.html`.
- `--no-create-404-redirect`: Do not create the `404.html` redirect.
```

--------------------------------

### text-forge epub CLI

Source: https://context7.com/shared-goals/text-forge/llms.txt

Builds only the EPUB using the text-forge CLI. Can specify configuration and build directories. Output files include combined Markdown, Pandoc-ready Markdown, metadata, and the final EPUB.

```bash
# Minimal usage (reads mkdocs.yml from current directory)
text-forge epub

# With explicit paths
text-forge epub --config path/to/mkdocs.yml --build-dir build/

# Output files generated in build/:
#   text_combined.md   — combined chapters
#   pandoc.md          — normalized for pandoc
#   book_meta.yml      — EPUB metadata
#   text_book.epub     — final EPUB3
```

--------------------------------

### text-forge epub CLI Command

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Command to build an EPUB from an MkDocs project. Specify the config file and build directory.

```bash
text-forge epub [OPTIONS]

Options:
  --config PATH      Path to mkdocs.yml (default: mkdocs.yml)
  --build-dir PATH   Build output directory (default: build)
```

--------------------------------

### build_epub_pipeline

Source: https://context7.com/shared-goals/text-forge/llms.txt

Orchestrates the four-step pipeline for generating an EPUB file: combining chapters, normalizing syntax, processing metadata, and finally generating the EPUB via pandoc. It returns the Path to the generated .epub file.

```APIDOC
## build_epub_pipeline — Full EPUB build

### Description
Orchestrates the four-step pipeline: combine chapters → normalize syntax → process metadata → generate EPUB via pandoc. Returns the `Path` to the generated `.epub` file.

### Method
```python
from pathlib import Path
from text_forge.build import build_epub_pipeline

epub_path = build_epub_pipeline(
    config_path=Path("mkdocs.yml"),
    build_dir=Path("build"),
    epub_filename="my_book.epub",       # default: "text_book.epub"
    combined_filename="combined.md",    # default: "text_combined.md"
)
# Outputs:
#   build/combined.md      — all chapters merged into one Markdown file
#   build/pandoc.md        — PyMdown syntax normalized for Pandoc
#   build/book_meta.yml    — EPUB metadata (title, author, edition, date)
#   build/my_book.epub     — final EPUB3 file
print(f"EPUB ready: {epub_path}")
```
```

--------------------------------

### MkDocs Plugin Theme Auto-configuration

Source: https://context7.com/shared-goals/text-forge/llms.txt

This Python code demonstrates the internal behavior of the TextForgePlugin for theme auto-configuration. It shows how the plugin inserts the Material theme override directory into mkdocs.yml's theme.dirs.

```python
# Internal behavior — triggered automatically by MkDocs on startup.
# Equivalent manual setup (when auto_configure_theme: false):

import sys, os
from pathlib import Path

theme_dir = Path(sys.prefix) / "share" / "text-forge" / "mkdocs" / "overrides"
# Then add to mkdocs.yml:
#   theme:
#     custom_dir: /path/to/overrides  # only supports one dir; plugin uses theme.dirs instead

```

--------------------------------

### Build EPUB with Pandoc

Source: https://context7.com/shared-goals/text-forge/llms.txt

Invokes pandoc directly for EPUB3 output, supporting TOC, metadata, custom CSS, cover images, and resource paths for image resolution. Ensure all paths are correctly specified.

```python
from pathlib import Path
from text_forge.build import build_epub_with_pandoc

build_epub_with_pandoc(
    markdown_path=Path("build/pandoc.md"),
    metadata_path=Path("build/book_meta.yml"),
    css_path=Path("share/text-forge/epub/epub.css"),  # bundled stylesheet
    cover_path=Path("text/img/cover.jpg"),             # None if no cover
    output_path=Path("build/text_book.epub"),
    docs_dir=Path("text"),                             # for resolving image paths
)
```

--------------------------------

### Common Text-Forge Development Commands

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Run formatting, linting, testing, internationalization checks, and release tasks using make commands.

```bash
make format      # Format code with ruff
make lint        # Run linters
make test        # Run tests with pytest
make check-i18n  # Validate translation keys
make release     # Interactive release (bump version, tag, push)
```

--------------------------------

### TextForgePlugin.on_serve - Live save endpoint

Source: https://context7.com/shared-goals/text-forge/llms.txt

During `mkdocs serve`, this endpoint intercepts POST requests to `/_text_forge/save` from the browser editor. It validates the file path and writes the content to disk, triggering MkDocs auto-reload.

```APIDOC
## POST /_text_forge/save

### Description
Intercepts save requests from the browser editor during `mkdocs serve` to update Markdown files.

### Method
POST

### Endpoint
/_text_forge/save

### Request Body
- **filePath** (string) - Required - The path of the file to save relative to the docs directory.
- **content** (string) - Required - The new content of the file.

### Request Example
```json
{
  "filePath": "chapter1.md",
  "content": "# Chapter 1\n\nUpdated content here."
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the save operation was successful.
- **path** (string) - The absolute path to the saved file.

#### Response Example
```json
{
  "success": true,
  "path": "/absolute/path/to/docs/chapter1.md"
}
```

#### Error Responses
- **400**: {"error": "Missing filePath or content"}
- **403**: {"error": "Invalid file path"} (Path traversal attempt blocked)
- **500**: {"error": "<exception message>"}
```

--------------------------------

### copy_build_artifacts

Source: https://context7.com/shared-goals/text-forge/llms.txt

Copies generated EPUB and combined Markdown files from the build directory to the MkDocs site root, making them available for download.

```APIDOC
## copy_build_artifacts

### Description
Copies outputs to site root. Copies the generated EPUB and combined Markdown file from the build directory into the MkDocs site root so they are available for download from the published site.

### Method Signature
```python
copy_build_artifacts(
    build_dir: Path,
    site_dir: Path,
    epub_filename: str,
    combined_filename: str
)
```

### Parameters
- **build_dir** (Path) - The directory containing the build artifacts.
- **site_dir** (Path) - The MkDocs site root directory.
- **epub_filename** (str) - The filename of the EPUB artifact.
- **combined_filename** (str) - The filename of the combined Markdown artifact.

### Request Example
```python
from pathlib import Path
from text_forge.build import copy_build_artifacts

copy_build_artifacts(
    build_dir=Path("build"),
    site_dir=Path("public"),
    epub_filename="text_book.epub",
    combined_filename="text_combined.md"
)
```
```

--------------------------------

### Create Legacy Redirect 404 Page

Source: https://context7.com/shared-goals/text-forge/llms.txt

Generates a `404.html` file in the site directory to redirect legacy `/ru/*` URLs to their non-prefixed equivalents and other 404s to the homepage. This is useful for GitHub Pages.

```python
from pathlib import Path
from text_forge.build import create_legacy_redirect_404

create_legacy_redirect_404(site_dir=Path("public"))
```

--------------------------------

### GitHub Actions Workflow for Publishing with Text Forge

Source: https://context7.com/shared-goals/text-forge/llms.txt

A GitHub Actions workflow that checks out code, uses the text-forge composite action to build documentation, and uploads the artifact for deployment. Requires specific permissions for Pages.

```yaml
# .github/workflows/publish.yml
name: Publish

on:
  push:
    branches: [master]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # full history for accurate revision dates

      - uses: shared-goals/text-forge@main
        id: forge
        with:
          mkdocs_config: mkdocs.yml
          docs_dir: text
          site_dir: public
          build_dir: build
          strict: 'true'
          copy_artifacts_into_docs: 'true'
          ensure_full_git_history: 'true'
          use_github_token_for_committers: 'true'
          # committers_token: ${{ secrets.MY_PAT }}  # optional override

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

# Action outputs (usable in subsequent steps):
#   ${{ steps.forge.outputs.combined_md }}  → build/text_combined.md
#   ${{ steps.forge.outputs.pandoc_md }}    → build/pandoc.md
#   ${{ steps.forge.outputs.epub }}         → build/text_book.epub

```

--------------------------------

### create_legacy_redirect_404

Source: https://context7.com/shared-goals/text-forge/llms.txt

Creates a `404.html` file in the site directory that implements JavaScript-based URL redirects for legacy paths and general 404 handling.

```APIDOC
## create_legacy_redirect_404

### Description
Creates a `404.html` in the site directory that uses JavaScript to redirect legacy `/ru/*` URL paths to their non-prefixed equivalents, and redirects all other 404s to the homepage after 2 seconds.

### Method Signature
```python
create_legacy_redirect_404(site_dir: Path)
```

### Parameters
- **site_dir** (Path) - The directory where the `404.html` file will be created.

### Request Example
```python
from pathlib import Path
from text_forge.build import create_legacy_redirect_404

create_legacy_redirect_404(site_dir=Path("public"))
```
```

--------------------------------

### text-forge epub

Source: https://context7.com/shared-goals/text-forge/llms.txt

Builds only the EPUB output using the `text-forge` CLI. It reads configuration from `mkdocs.yml` by default.

```APIDOC
## text-forge epub

### Description
Builds EPUB only. Reads `mkdocs.yml` from the current directory by default.

### Usage
```bash
# Minimal usage
text-forge epub

# With explicit paths
text-forge epub --config path/to/mkdocs.yml --build-dir build/
```

### Output Files
- `build/text_combined.md`: Combined chapters.
- `build/pandoc.md`: Normalized Markdown for Pandoc.
- `build/book_meta.yml`: EPUB metadata.
- `build/text_book.epub`: Final EPUB3 output.
```

--------------------------------

### Configure text-forge Plugin in mkdocs.yml

Source: https://context7.com/shared-goals/text-forge/llms.txt

Register the text-forge plugin and configure its various options in your mkdocs.yml file. This includes settings for the live editor, EPUB metadata, and theme overrides.

```yaml
# mkdocs.yml
site_name: "My Book"
site_url: "https://example.com/"
site_author: "Author Name"
site_description: "A great book"
docs_dir: text
site_dir: public

plugins:
  - text-forge:
      # Live editor (browser-based Markdown editor with Pyodide preview)
      editor_enabled: true

      # Wrap ASCII emoticons like :-) in <span class="md-nobr"> to prevent line-breaks
      nobr_emoticons_enabled: true

      # Show EPUB download button in page header
      downloads_enabled: true

      # AI-readable: show "Open in Grok" button; set base URL and prompt template
      ai_readable_base_url: "https://grok.com/?q="
      ai_readable_prompt: "Summarize this article: "

      # Material theme overrides auto-applied (set false to manage custom_dir yourself)
      auto_configure_theme: true

      # EPUB metadata (overrides site_name / site_author / etc.)
      epub_title: "My Book Title"
      epub_subtitle: "Subtitle Here"
      epub_author: "Author Name"
      epub_identifier: "https://example.com/"
      epub_publisher: "Publisher"
      epub_rights: "© 2024 Author Name"

      # Output filenames
      epub_filename: "text_book.epub"
      combined_filename: "text_combined.md"

      # UI label for the "source file" link
      source_file_published_title: "Published"

```

--------------------------------

### Generate AI Summarization Source with Index

Source: https://context7.com/shared-goals/text-forge/llms.txt

Concatenates MkDocs chapters into a single file suitable for AI summarization, adding FILE markers. Optionally generates a JSON index of headings for navigation.

```bash
python scripts/mkdocs-combine.py mkdocs.yml \
  --mode summary \
  --exclude p3-summary.md \
  --index-output build/heading_index.json \
  > build/summary_source.md
```

--------------------------------

### Generate EPUB Metadata YAML

Source: https://context7.com/shared-goals/text-forge/llms.txt

Reads `mkdocs.yml` and `text-forge` plugin configuration to extract git tag and commit date, then renders a `book_meta.yml` file with all necessary EPUB metadata fields.

```python
from pathlib import Path
from text_forge.build import process_epub_metadata

process_epub_metadata(
    config_path=Path("mkdocs.yml"),
    output_path=Path("build/book_meta.yml"),
)
# Produces book_meta.yml with fields like:
#   title: "My Book"
#   subtitle: "Subtitle"
#   author: "Author Name"
#   edition: "v0.5.0, 15 января 2025"  ← git tag + Russian-locale date
#   date: "2025-01-15"
#   rights: "© 2025 Author Name"
```

--------------------------------

### Use text-forge as GitHub Action

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Integrate text-forge into your GitHub Actions workflow for automated builds.

```yaml
# .github/workflows/publish.yml
- uses: shared-goals/text-forge@main
  with:
    mkdocs_config: mkdocs.yml
    docs_dir: text/ru
    site_dir: public/ru
```

--------------------------------

### Clean Build Outputs

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Removes generated output files from the build process.

```bash
cd whattodo && make clean
```

--------------------------------

### load_mkdocs_config

Source: https://context7.com/shared-goals/text-forge/llms.txt

Loads a MkDocs YAML configuration file (`mkdocs.yml`) with support for MkDocs-specific custom tags like `!ENV`.

```APIDOC
## load_mkdocs_config

### Description
Loads a MkDocs YAML configuration file with graceful handling of MkDocs-specific custom tags like `!ENV`.

### Method Signature
```python
load_mkdocs_config(config_path: Path) -> dict
```

### Parameters
- **config_path** (Path) - Path to the `mkdocs.yml` configuration file.

### Response
#### Success Response (dict)
- Returns a dictionary representing the parsed MkDocs configuration.

### Request Example
```python
from pathlib import Path
from text_forge.build import load_mkdocs_config

config = load_mkdocs_config(Path("mkdocs.yml"))

print(config["site_name"])
print(config["docs_dir"])
print(config["site_url"])

# Access plugin settings:
for plugin in config.get("plugins", []):
    if isinstance(plugin, dict) and "text-forge" in plugin:
        tf_config = plugin["text-forge"]
        print(tf_config.get("epub_title"))
```
```

--------------------------------

### Combine MkDocs Chapters to Markdown

Source: https://context7.com/shared-goals/text-forge/llms.txt

Combines all chapters from an MkDocs navigation into a single Markdown file, adjusting heading levels and rewriting internal links. Preserves frontmatter from the first chapter.

```bash
python scripts/mkdocs-combine.py mkdocs.yml > build/text_combined.md
```

--------------------------------

### Convert PyMdown to Pandoc Markdown Syntax

Source: https://context7.com/shared-goals/text-forge/llms.txt

Converts PyMdown Extensions syntax to Pandoc-compatible fenced div syntax using `pandoc` and a Lua filter. This is useful for ensuring compatibility with Pandoc's processing.

```python
from pathlib import Path
from text_forge.build import normalize_markdown

normalize_markdown(
    input_path=Path("build/text_combined.md"),
    output_path=Path("build/pandoc.md"),
)
# Transforms:
#   /// situation\n content \n///   →   ::: situation\n content \n:::
#   ![img](img/photo.jpg){width=75%} →  ![img](img/photo.jpg){width="75%" loading=lazy}
```

--------------------------------

### Configure text-forge MkDocs Plugin

Source: https://github.com/shared-goals/text-forge/blob/main/README.md

Add the text-forge plugin to your mkdocs.yml configuration file to enable its features.

```yaml
plugins:
  - text-forge:
      editor_enabled: true          # Enable live editor (default: true)
      nobr_emoticons_enabled: true  # Wrap emoticons in no-break spans (default: true)
      downloads_enabled: false      # Show EPUB download button (default: false)
      ai_readable_enabled: false    # Show "Open in Perplexity" button (default: false)
      epub_title: "My Book"         # EPUB metadata (optional)
      epub_author: "Author Name"
      # ... other epub_* options
```

--------------------------------

### Expose Plugin Config to Jinja Templates

Source: https://context7.com/shared-goals/text-forge/llms.txt

Exposes plugin configuration to MkDocs Jinja templates for conditional rendering of features in custom partials.

```jinja2
{# mkdocs/overrides/partials/header.html — using injected globals #}
{% if text_forge_downloads_enabled %}
  <a href="{{ text_forge_epub_filename }}" download>Download EPUB</a>
{% endif %}

{% if text_forge_editor_enabled %}
  {% include "partials/editor.html" %}
{% endif %}

{# Available globals:
   text_forge_editor_enabled        bool
   text_forge_downloads_enabled     bool
   text_forge_ai_readable_prompt    str
   text_forge_ai_readable_base_url  str
   text_forge_epub_filename         str   (default: "text_book.epub")
   text_forge_combined_filename     str   (default: "text_combined.md")
   text_forge_source_file_published_title  str
   text_forge_epub                  dict  {title, subtitle, author, identifier, publisher, rights}
#}
```

--------------------------------

### build_epub_with_pandoc

Source: https://context7.com/shared-goals/text-forge/llms.txt

Invokes pandoc directly to build an EPUB3 output. This function supports TOC generation, metadata files, custom CSS, optional cover images, and resource paths for image resolution.

```APIDOC
## build_epub_with_pandoc

### Description
Calls `pandoc` directly with epub3 output, TOC generation, metadata file, custom CSS, optional cover image, and resource-path for image resolution.

### Method Signature
```python
build_epub_with_pandoc(
    markdown_path: Path,
    metadata_path: Path,
    css_path: Path,
    cover_path: Optional[Path] = None,
    output_path: Path,
    docs_dir: Path
)
```

### Parameters
- **markdown_path** (Path) - Path to the input Markdown file.
- **metadata_path** (Path) - Path to the YAML metadata file.
- **css_path** (Path) - Path to the custom CSS file for EPUB styling.
- **cover_path** (Optional[Path]) - Optional path to the cover image file.
- **output_path** (Path) - Path for the generated EPUB file.
- **docs_dir** (Path) - Directory for resolving image paths within the Markdown.

### Request Example
```python
from pathlib import Path
from text_forge.build import build_epub_with_pandoc

build_epub_with_pandoc(
    markdown_path=Path("build/pandoc.md"),
    metadata_path=Path("build/book_meta.yml"),
    css_path=Path("share/text-forge/epub/epub.css"),
    cover_path=Path("text/img/cover.jpg"),
    output_path=Path("build/text_book.epub"),
    docs_dir=Path("text")
)
```
```

--------------------------------

### Run Pytest Tests Matching a Pattern

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Executes pytest tests that match a given pattern (e.g., 'combined', 'pandoc', 'consistency'). Uses uv for environment management.

```bash
uv run pytest tests/test_pipeline.py -k combined -v
```

```bash
uv run pytest tests/test_pipeline.py -k pandoc -v
```

```bash
uv run pytest tests/test_pipeline.py -k consistency -v
```

--------------------------------

### normalize_markdown

Source: https://context7.com/shared-goals/text-forge/llms.txt

Converts PyMdown Extensions syntax to Pandoc-compatible fenced div syntax using a Lua filter. This is useful for ensuring compatibility with Pandoc when generating EPUBs.

```APIDOC
## normalize_markdown — PyMdown → Pandoc syntax

### Description
Runs `pandoc` with the bundled `pymdown-pandoc.lua` Lua filter to convert PyMdown Extensions syntax (e.g. `/// admonition`) into Pandoc-compatible fenced div syntax (`::: admonition`).

### Method
```python
from pathlib import Path
from text_forge.build import normalize_markdown

normalize_markdown(
    input_path=Path("build/text_combined.md"),
    output_path=Path("build/pandoc.md"),
)
# Transforms:
#   /// situation\n content \n///   →   ::: situation\n content \n:::
#   ![img](img/photo.jpg){width=75%} →  ![img](img/photo.jpg){width="75%" loading=lazy}
```
```

--------------------------------

### Run a Specific Pytest Test

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Executes a single pytest test case, identified by its name. Uses uv for environment management.

```bash
uv run pytest tests/test_pipeline.py -k test_combined_has_all_chapters -v
```

--------------------------------

### process_epub_metadata

Source: https://context7.com/shared-goals/text-forge/llms.txt

Generates a `book_meta.yml` file containing all necessary EPUB metadata. It reads information from `mkdocs.yml` and extracts git tag and commit date for fields like title, author, edition, and rights.

```APIDOC
## process_epub_metadata — Generate EPUB metadata YAML

### Description
Reads `mkdocs.yml` (including `text-forge` plugin config), extracts git tag and commit date, and renders a `book_meta.yml` file with all EPUB metadata fields filled in.

### Method
```python
from pathlib import Path
from text_forge.build import process_epub_metadata

process_epub_metadata(
    config_path=Path("mkdocs.yml"),
    output_path=Path("build/book_meta.yml"),
)
# Produces book_meta.yml with fields like:
#   title: "My Book"
#   subtitle: "Subtitle"
#   author: "Author Name"
#   edition: "v0.5.0, 15 января 2025"  ← git tag + Russian-locale date
#   date: "2025-01-15"
#   rights: "© 2025 Author Name"
```
```

--------------------------------

### Check Internationalization Translations

Source: https://github.com/shared-goals/text-forge/blob/main/AGENTS.md

Validates translations.json against HTML/JS usage. Requires the check_i18n.py script.

```bash
make check-i18n
```

--------------------------------

### Enable Giscus Comments and Theme Sync

Source: https://github.com/shared-goals/text-forge/blob/main/mkdocs/overrides/partials/comments.html

This Jinja2 template code enables Giscus comments if page.meta.comments is true and synchronizes the Giscus theme with the Material theme. It requires Giscus repository identifiers to be configured in mkdocs.yml.

```html
{# Shared template (text-forge). Notes: - Rendered only when page.meta.comments is truthy. - Giscus repo identifiers are provided by the content repo via mkdocs.yml: extra.giscus.repo extra.giscus.repo_id extra.giscus.category extra.giscus.category_id - If identifiers are not provided (e.g., env vars not set), comments are hidden. #} {% if page.meta.comments %} {% set giscus = config.extra.get("giscus", {}) %} {% set repo = giscus.get("repo") %} {% set repo_id = giscus.get("repo_id") %} {% set category = giscus.get("category") %} {% set category_id = giscus.get("category_id") %} {% if repo and repo_id and category and category_id %}

{{ lang.t("meta.comments") }}
-----------------------------

{# Synchronize Giscus theme with Material palette #} var giscus = document.querySelector("script\[src\*=giscus\]") // Set palette on initial load var palette = __md_get("__palette") if (palette && typeof palette.color === "object") { var theme = palette.color.scheme === "slate" ? "transparent_dark" : "light" // Instruct Giscus to set theme giscus.setAttribute("data-theme", theme) } // Register event handlers after document loaded document.addEventListener("DOMContentLoaded", function() { var ref = document.querySelector("a[data-md-component=palette]") if (!ref) return ref.addEventListener("change", function() { var palette = __md_get("__palette") if (palette && typeof palette.color === "object") { var theme = palette.color.scheme === "slate" ? "transparent_dark" : "light" // Instruct Giscus to change theme var frame = document.querySelector(".giscus-frame") if (!frame) return frame.contentWindow.postMessage( { giscus: { setConfig: { theme } } }, "https://giscus.app" ) } }) }) {% endif %} {% endif %}
```

--------------------------------

### Process Single Markdown File with Heading Shift

Source: https://context7.com/shared-goals/text-forge/llms.txt

Shifts heading levels in a single Markdown file by a specified amount and rewrites internal links accordingly. Useful for processing individual chapters or documents.

```bash
python scripts/mkdocs-combine.py chapter1.md --level 1 > output.md
```

--------------------------------

### combine_chapters

Source: https://context7.com/shared-goals/text-forge/llms.txt

Merges all Markdown chapters into a single combined Markdown file based on the MkDocs navigation structure. It adjusts heading levels, rewrites internal links, and appends chapter-date blocks.

```APIDOC
## combine_chapters — Merge Markdown chapters

### Description
Runs `scripts/mkdocs-combine.py` with the MkDocs config to produce a single combined Markdown file from the `nav:` structure.

### Method
```python
from pathlib import Path
from text_forge.build import combine_chapters

combine_chapters(
    config_path=Path("mkdocs.yml"),
    output_path=Path("build/text_combined.md"),
)
# Reads docs_dir and nav from mkdocs.yml, concatenates all chapters,
# shifts heading levels to match nav hierarchy, rewrites internal links
# from file references to anchor references, and appends chapter-dates blocks.
```
```

--------------------------------

### Merge Markdown Chapters

Source: https://context7.com/shared-goals/text-forge/llms.txt

Merges Markdown chapters into a single combined file using the MkDocs configuration. It shifts heading levels, rewrites internal links, and appends chapter-dates blocks.

```python
from pathlib import Path
from text_forge.build import combine_chapters

combine_chapters(
    config_path=Path("mkdocs.yml"),
    output_path=Path("build/text_combined.md"),
)
# Reads docs_dir and nav from mkdocs.yml, concatenates all chapters,
# shifts heading levels to match nav hierarchy, rewrites internal links
# from file references to anchor references, and appends chapter-dates blocks.
```

--------------------------------

### MkDocs Hook for No-Break Emoticons

Source: https://context7.com/shared-goals/text-forge/llms.txt

An MkDocs hook that automatically wraps ASCII emoticons in `<span class="md-nobr">` tags to prevent line breaks. It is automatically registered when `nobr_emoticons_enabled` is true in the MkDocs configuration.

```python
# Processed automatically on every page during mkdocs build/serve.
# Manually testable:
from mkdocs.hooks import nobr_emoticons  # after text-forge install

result = nobr_emoticons.on_page_markdown(
    markdown="Hello :-) how are you ;-) today",
    page=None, config=None, files=None
)
# result:
# 'Hello <span class="md-nobr">:-)</span> how are you <span class="md-nobr">;-)</span> today'

# Covered emoticons: :-)  :-(  ;-)  :-D  :-P  :)  :(  ;)
# Idempotent: already-wrapped spans are not double-wrapped

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.