# 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.