The "/doc" page:
CHECKIN can be either tag or hash prefix or timestamp identifying a particular check-in, or the name of a branch (meaning the most recent check-in on that branch) or one of various magic words:
- "tip"
- means the most recent check-in
- "ckout"
- means the current check-out, if the server is run from within a check-out, otherwise it is the same as "tip"
- "latest"
- means use the most recent check-in for the document regardless of what branch it occurs on.
FILE is the name of a file to delivered up as a webpage. FILE is relative to the root of the source tree of the repository. The FILE must be a part of CHECKIN, except when CHECKIN=="ckout" when FILE is read directly from disk and need not be a managed file. For /uv, FILE can also be the hash of the unversioned file.
The "ckout" CHECKIN is intended for development - to provide a mechanism for looking at what a file will look like using the /doc webpage after it gets checked in. Some commands like "fossil ui", "fossil server", and "fossil http" accept an argument "--ckout-alias NAME" when allows NAME to be understood as an alias for "ckout". On a site with many embedded hyperlinks to /doc/trunk/... one can run with "--ckout-alias trunk" to simulate what the pending changes will look like after they are checked in. The NAME alias is stored in g.zCkoutAlias.
The file extension is used to decide how to render the file.
If FILE ends in "/" then the names "FILE/index.html", "FILE/index.wiki", and "FILE/index.md" are tried in that order. If the binary was compiled with TH1 embedded documentation support and the "th1-docs" setting is enabled, the name "FILE/index.th1" is also tried. If none of those are found, then FILE is completely replaced by "404.md" and tried. If that is not found, then a default 404 screen is generated.
If the file's mimetype is "text/x-fossil-wiki" or "text/x-markdown" then headers and footers are added. If the document has mimetype text/html then headers and footers are usually not added. However, if a "text/html" document begins with the following div:
<div class='fossil-doc' data-title='TEXT'>
then headers and footers are supplied. The optional data-title field specifies the title of the document in that case.
For fossil-doc documents and for markdown documents, text of the form: "href='$ROOT/" or "action='$ROOT" has the $ROOT name expanded to the top-level of the repository.