Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#34 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

@aRustyDev ci sta già lavorando.

Dal 5/1/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

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

Lingua principale
Rust
Stelle
0
Fork
1
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di aRustyDev/mdbook-htmx

Tutte le issue di aRustyDev/mdbook-htmx

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.