Module Wodoc.Config

type entry = {
  1. label : string;
    (*

    visible text

    *)
  2. path : string;
    (*

    href: relative to the version root (filled with base), unless it is absolute (/…) or a URL (http(s)://…), which is emitted verbatim

    *)
  3. current : string;
    (*

    data-wodoc-page id (highlighted on its own pages)

    *)
}
type 'tree item =
  1. | Group of 'tree group
  2. | Page_tree of 'tree
    (*

    (page-tree [<index>]): the page tree odoc builds from the manual's directories (odoc-pages/<dir>/, ordered by @children_order), below the page <index> (default index.html), as odoc_driver writes it in sidebar.json, without its library and source entries. Expanded before rendering, so the left column follows the same tree as ocaml.org.

    *)
and 'tree group = {
  1. heading : string;
  2. index : string option;
    (*

    the page the heading links to (a directory of a page tree whose index page is clickable), relative to the version root

    *)
  3. items : 'tree item list;
}

a sub-heading (<h4>) and its nested items, one indent level deeper. Lets a manual nav reproduce a multi-level menu (sections, subsections, page links), as the old wikicréole menu expressed with ==/===.

type expanded = |
type 'tree section = {
  1. heading : string;
    (*

    the <h3> label of this left-nav block

    *)
  2. api : bool;
    (*

    api-section -> class "api-nav"; else "api-nav manual-nav"

    *)
  3. items : 'tree item list;
}
type blog = {
  1. dir : string;
    (*

    directory of post sources, named YYYY-MM-DD-slug.mld (the date is the publication date; posts sort newest-first on it). Relative to the config file's directory. The posts are plain .mld (author from @author).

    *)
  2. out : string;
    (*

    output subdirectory under the version root, e.g. "blog": posts deploy as <out>/blog/<slug>.html

    *)
  3. heading : string;
    (*

    the generated left-nav section <h3> label, e.g. "Blog"

    *)
  4. latest : int;
    (*

    how many recent posts the {%wodoc:blog-latest%} marker expands to on the landing page

    *)
}

an ultra-simple blog: a directory of dated .mld posts that wodoc builds like any other page, auto-listing them in a generated left-nav section and exposing the most recent ones to the landing via the {%wodoc:blog-latest%} marker. Generic (no project hardcoding); None when the project declares no (blog …).

type cs_side = {
  1. side : string;
    (*

    key, e.g. "server": body class wodoc-server, switch id

    *)
  2. lib : string;
    (*

    odoc subtree dir / Nav.api ~lib, e.g. "eliom.server"

    *)
  3. indexdoc : string;
    (*

    curated index path (relative to the build cwd)

    *)
  4. heading : string;
    (*

    API-nav heading + switch-button label, e.g. "Server API"

    *)
  5. wrapper : string;
    (*

    Nav.api ~wrapper / page wrapper module, e.g. "Eliom"

    *)
  6. skip : string list;
    (*

    section titles to omit (Nav.api ~skip)

    *)
}

one API "side" of a client/server project (eliom/toolkit/start): the <pkg>.server / <pkg>.client / <pkg>.ppx library, whose curated index becomes a section-grouped module nav (via Nav.api). The side also drives a body colour class (wodoc-<side>) and a switch button.

type t = {
  1. project : string;
    (*

    package / project id, e.g. "ocsipersist"

    *)
  2. title : string;
    (*

    sub-project label by the logo, e.g. "Ocsipersist"

    *)
  3. url_prefix : string;
    (*

    absolute URL path the site is published at, e.g. "/ocsipersist"; used by the version selector to switch versions

    *)
  4. menu_current : string;
    (*

    project id highlighted in the shared top menu

    *)
  5. packages : string list;
    (*

    odoc output subtrees to assemble, in order

    *)
  6. landing : string;
    (*

    index.html redirect target, e.g. "ocsipersist/index.html"

    *)
  7. highlight : string option;
    (*

    project highlight.js to ship, if any

    *)
  8. profile : string option;
    (*

    dune build profile (e.g. "release")

    *)
  9. odoc_driver : string option;
    (*

    when set, build the API with odoc_driver <pkg> --remap (the engine ocaml.org uses) instead of dune build @doc: needed for a client/server package whose <pkg>.server/<pkg>.client libraries share module names and would collide under dune build @doc (eliom, ocsigen-toolkit, ocsigen-start).

    *)
  10. doc_manual : bool;
    (*

    also build the @doc-manual alias (examples)

    *)
  11. manual_files : string option;
    (*

    package dir to receive manual/files (examples, images)

    *)
  12. siblings : (string * string list) list;
    (*

    resolve-refs sibling table

    *)
  13. nav : string section list option;
    (*

    the (nav …) stanza; None when the config has none: the left column then shows the manual tree odoc builds, as (nav (section <title> (page-tree))) would, if odoc_driver wrote its sidebar.json

    *)
  14. client_server : cs_side list;
    (*

    when non-empty, the project is client/server: instead of one nav from nav, wodoc builds a per-side API nav from each side's curated index, shows a client/server switch, and colours the body by side. The manual nav is shared, taken from nav's manual ((section …)) blocks.

    *)
  15. hosted : (string * (string * Resolve.layout * string)) list;
    (*

    cross-project resolve-refs table (resolve-refs --hosted): package -> (deploy dir, layout, wrapper module). Rewrites sibling Ocsigen projects' ocaml.org xrefs to relative links into their wodoc docs. See Resolve.layout for the layout token (multilib/root/subdir).

    *)
  16. manual_root : bool;
    (*

    deploy the package's pages at the version ROOT instead of under a <package>/ subdirectory: strip the leading <package>/ segment from output paths, the landing and the nav links. Makes a single-package dune build @doc project (ocsigenserver, i18n) match the layout of odoc-driver projects (eliom: manual at the version root, e.g. /ocsigenserver/latest/config.html) so cross-project links resolve. The package's internal relative links are preserved (the same prefix is stripped from every page).

    *)
  17. mld_dir : string option;
    (*

    direct-mld build (a manual-only / archived project with no dune build @doc): compile every .mld in this dir straight with odoc (preprocess -> compile -> link -> html-generate). The pages are the manual; the landing index.html is a real page (no redirect).

    *)
  18. mld_package : string;
    (*

    odoc --package for the direct-mld compile (the src subtree)

    *)
  19. flat : bool;
    (*

    assemble --flat (content straddling odoc's preamble boundary)

    *)
  20. static_copy : (string * string) list;
    (*

    verbatim copies into the output: (source path, dest under <out>), e.g. a frozen API snapshot, or a manual image

    *)
  21. blog : blog option;
    (*

    an optional (blog …) section (see blog)

    *)
  22. markdown : bool;
    (*

    emit the Markdown twin of every page + the llms.txt/llms-full.txt index (for AI/LLM consumption). On by default; (markdown false) turns it off.

    *)
  23. css : string list;
    (*

    stylesheet hrefs for the page <head>. Each is emitted verbatim when absolute (/…) or a URL, else made per-page relative ({{base}}/…) and, when it names a file next to the config, copied into the output, so a project can ship a self-contained theme that works at any deploy path. [] (the default) ships wodoc's built-in default theme as wodoc.css.

    *)
}
val retired : (string * string) list
val check_keys : where:string -> string list -> Sexp.t list -> unit
val parse_entry : Sexp.t -> entry
val parse_items : Sexp.t list -> string item list
val parse_section : bool -> Sexp.t -> string section
val parse_nav_blocks : Sexp.t list -> string section list
val parse_nav : Sexp.t list -> string section list option
val nav_of_string : string -> string section list option
val parse_siblings : Sexp.t list -> (string * string list) list
val parse_client_server : Sexp.t list -> cs_side list
val parse_hosted : Sexp.t list -> (string * (string * Resolve.layout * string)) list
val parse_blog : Sexp.t list -> blog option
val check_static_dest : string -> string
val parse_static_copy : Sexp.t list -> (string * string) list
val stanza_names : string list
val of_string : string -> t