Authoring: what survives on ocaml.org
The {%wodoc:...%} target is unknown to stock odoc, so it is dropped when the same sources are built with a stock odoc (for example on ocaml.org). This is the whole point (the docs stay clean and semantic there), but it means you must choose, per construct, whether something is content (must survive) or presentation (may vanish).
The rule
- Must be meaningful on ocaml.org → use native odoc (never a dropped marker): links
{{:url}text}, content images{image:url}, text, code, lists, tables, headings. These render identically with or without wodoc. {%wodoc:@ ...%}only adds attributes to a native element: the element (and its content) survives on ocaml.org, only the class is absent there.- Drop on ocaml.org →
{%wodoc:div/span/a/...%}: purely presentational wrappers and chrome (layout containers, whole-block clickable wrappers). The native content inside still survives on ocaml.org; only the shell disappears.
In particular, prefer native links so they keep working on ocaml.org; reserve {%wodoc:a%} for making a whole block clickable (which native odoc cannot express), keeping a native link inside when the target should remain reachable.
Cross-project references
The manual you write here is also published on ocaml.org, so it must not contain links that only resolve on ocsigen.org:
- API of another package → a native odoc reference, e.g.
{!Lwt.t}. odoc resolves it across packages on ocaml.org and our renderer redirects it to ocsigen.org. - A manual or project page of another Ocsigen project → a relative link
../<project>/<page>.html(correct on the final flat ocsigen.org layout). - Never an absolute
https://ocsigen.org/…or/wodoc/…link for content: the first does not resolve on ocaml.org and the second only exists during migration previews.
The chrome of the site template (header, menus) may stay absolute: it only exists on ocsigen.org.