Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

docs(mdbook-htmx): book.json / manifest.json

Abierto
  • ¿Algo no está bien?
#34 0 comentarios 0 reacciones 1 asignado Ver en GitHub

@aRustyDev ya está trabajando en esto.

Desde el 5/1/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

documentation

Manifest Reference

This document provides a complete reference for the manifest.json file generated by mdbook-htmx.

Overview

The manifest is a JSON file that describes all pages, their metadata, navigation structure, and authorization requirements. It serves as the contract between the build-time generator and runtime server.

{
  "$schema": "https://schemas.arusty.dev/mdbook-htmx/manifest.schema.json",
  "version": "1.0.0",
  "generated": "2026-01-04T12:00:00Z",
  "book": { ... },
  "pages": [ ... ],
  "navigation": { ... }
}

Schema Reference

Manifests are validated against the JSON Schema at:

https://schemas.arusty.dev/mdbook-htmx/manifest.schema.json

Top-Level Fields

Field Type Required Description
$schema string No JSON Schema URL for validation
version string Yes Manifest schema version (semver)
generated string Yes ISO 8601 build timestamp
book object Yes Book-level metadata
pages array Yes Array of page entries
navigation object Yes Navigation structure
authn object No Authentication configuration
scopes object No Scope configuration

Version Field

The version field uses semantic versioning:

{
  "version": "1.0.0"
}
Version Part When to Increment
Major Breaking changes to manifest structure
Minor New optional fields added
Patch Bug fixes, documentation updates

Server implementations should:

  1. Parse the major version
  2. Reject manifests with unsupported major versions
  3. Ignore unknown fields for forward compatibility

Book Metadata (book)

Field Type Description
title string Book title
description string Book description
authors string[] Author names
language string Language code (e.g., "en")
baseUrl string Base URL for the documentation
Example
{
  "book": {
    "title": "My Documentation",
    "description": "Complete reference for My Project",
    "authors": ["John Doe", "Jane Smith"],
    "language": "en",
    "baseUrl": "/docs"
  }
}

Pages Array (pages)

Each page entry contains:

Field Type Required Description
id string Yes Unique page identifier
path string Yes URL path
title string Yes Page title
file string Yes Path to full HTML file
fragment string No Path to fragment (content only)
section string No Parent section name
auth object No Authorization requirements
htmx object No HTMX behavior configuration
search object No Search index metadata
scopes string[] No Audience scopes
lastModified string No ISO 8601 last modified date
Page Example
{
  "pages": [
    {
      "id": "getting-started",
      "path": "/docs/getting-started",
      "title": "Getting Started",
      "file": "pages/getting-started.html",
      "fragment": "fragments/getting-started.html",
      "section": "Introduction",
      "auth": {
        "access": "public"
      },
      "htmx": {
        "preload": true,
        "cache": 3600
      },
      "search": {
        "indexed": true,
        "weight": 2.0
      },
      "scopes": ["all", "developers"],
      "lastModified": "2026-01-04T10:30:00Z"
    }
  ]
}
Page Auth Object
Field Type Default Description
access enum "public" Access level
roles string[] [] Required roles
fallback string /auth/access-denied Unauthorized redirect
Page HTMX Object
Field Type Default Description
lazy boolean false Lazy load content
preload boolean false Preload on hover
cache integer 0 Cache-Control max-age
swap string "innerHTML" Swap strategy
Page Search Object
Field Type Default Description
indexed boolean true Include in search
weight number 1.0 Ranking weight
keywords string[] [] Additional keywords
excerpt string (auto) Search result excerpt

Navigation (navigation)

Field Type Description
chapters array Hierarchical chapter structure
flat array Flat list of all pages
Chapters Structure
{
  "navigation": {
    "chapters": [
      {
        "title": "Introduction",
        "path": "/docs",
        "children": [
          {
            "title": "Getting Started",
            "path": "/docs/getting-started",
            "children": []
          },
          {
            "title": "Installation",
            "path": "/docs/installation",
            "children": []
          }
        ]
      }
    ]
  }
}
Flat List
{
  "navigation": {
    "flat": [
      { "path": "/docs", "title": "Introduction" },
      { "path": "/docs/getting-started", "title": "Getting Started" },
      { "path": "/docs/installation", "title": "Installation" }
    ]
  }
}

Authentication Configuration (authn)

Optional authentication metadata for server reference.

Field Type Description
enabled boolean Whether auth is enabled
signinPage string Path to sign-in page
signinPartial string Path to sign-in partial
signoutPage string Path to sign-out page
provider string Auth provider hint
Example
{
  "authn": {
    "enabled": true,
    "signinPage": "/auth/signin",
    "signinPartial": "partials/signin.html",
    "signoutPage": "/auth/signout",
    "provider": "jwt"
  }
}

Scope Configuration (scopes)

Field Type Description
enabled boolean Whether scopes are enabled
available string[] List of available scopes
default string Default scope
globalScopes string[] Scopes in main index
Example
{
  "scopes": {
    "enabled": true,
    "available": ["all", "developers", "managers", "sre"],
    "default": "all",
    "globalScopes": ["all"]
  }
}

Scope-Filtered Manifests

When scopes are enabled, mdbook-htmx generates filtered manifests:

manifest.json              # Full manifest (all pages)
manifest.developers.json   # Only pages with 'developers' scope
manifest.managers.json     # Only pages with 'managers' scope
manifest.sre.json          # Only pages with 'sre' scope

Each filtered manifest:

  • Contains only pages matching the scope
  • Has scope field set to the filter scope
  • Includes filtered navigation structure

Complete Example

{
  "$schema": "https://schemas.arusty.dev/mdbook-htmx/manifest.schema.json",
  "version": "1.0.0",
  "generated": "2026-01-04T12:00:00Z",
  "book": {
    "title": "Platform Documentation",
    "description": "Complete platform reference",
    "authors": ["Platform Team"],
    "language": "en",
    "baseUrl": "/docs"
  },
  "pages": [
    {
      "id": "index",
      "path": "/docs",
      "title": "Introduction",
      "file": "pages/index.html",
      "fragment": "fragments/index.html",
      "auth": { "access": "public" },
      "scopes": ["all"]
    },
    {
      "id": "api-reference",
      "path": "/docs/api",
      "title": "API Reference",
      "file": "pages/api.html",
      "fragment": "fragments/api.html",
      "section": "Developer Guide",
      "auth": {
        "access": "roles",
        "roles": ["developer", "admin"]
      },
      "scopes": ["developers"]
    }
  ],
  "navigation": {
    "chapters": [
      {
        "title": "Introduction",
        "path": "/docs",
        "children": []
      },
      {
        "title": "Developer Guide",
        "path": "/docs/dev",
        "children": [
          {
            "title": "API Reference",
            "path": "/docs/api",
            "children": []
          }
        ]
      }
    ],
    "flat": [
      { "path": "/docs", "title": "Introduction" },
      { "path": "/docs/api", "title": "API Reference" }
    ]
  },
  "authn": {
    "enabled": true,
    "signinPage": "/auth/signin",
    "provider": "jwt"
  },
  "scopes": {
    "enabled": true,
    "available": ["all", "developers", "managers"],
    "default": "all"
  }
}

Server Usage

Loading the Manifest
import manifest from './manifest.json';

// Type-safe access
interface Manifest {
  version: string;
  pages: Page[];
  navigation: Navigation;
}

const m: Manifest = manifest;
Finding a Page
function findPage(path: string): Page | undefined {
  return manifest.pages.find(p => p.path === path);
}
Checking Authorization
function canAccess(page: Page, user: User): boolean {
  if (page.auth.access === 'public') return true;
  if (page.auth.access === 'authenticated') return !!user;
  if (page.auth.access === 'roles') {
    return page.auth.roles.some(role => user.hasRole(role));
  }
  return false;
}
Version Checking
function isCompatible(manifest: Manifest): boolean {
  const [major] = manifest.version.split('.');
  return parseInt(major) === 1; // Server supports v1.x.x
}

Related Documentation

Lenguaje dominante
Rust
Estrellas
0
Forks
1
Sin PR fusionados en 30 d

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de aRustyDev/mdbook-htmx

Todos los issues de aRustyDev/mdbook-htmx

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.