The "fsdocs" tool allows documentation for a site to be built
from content in a docs
directory. The expected structure for a docs
directory is
|
Processing is by these two commands:
dotnet fsdocs build
dotnet fsdocs watch
The output goes in output/
by default. Processing is recursive, making this a form of static site generation.
The input directory may contain literate scripts and markdown content.
Content that is not *.fsx
or *.md
is copied across.
By default additional content such as fsdocs-search.js
, fsdocs-tips.js
and fsdocs-styles.css
are included in the
the content
directory of the output. This can be suppressed with --nodefaultcontent
or by having your own
copy of this content in your content
directory.
Any file or directory beginning with .
is ignored.
Each content file can have optional frontmatter. This determines the navigation bar title, categorization and ordering.
For markdown, the format is:
---
title: Some Title
category: Some Category
categoryindex: 2
index: 3
---
For F# scripts the frontmatter is in this form:
(**
---
title: A Literate Script
category: Examples
categoryindex: 2
index: 1
---
*)
All entries are optional.
The categoryindex
determines the ordering of categories.
The index
determines the ordering of within each category.
The title
is used in the navigation bar instead of any title inferred from the document.
If an input is used in markdown as a target of a markdown direct link then that is replaced by the output file. For example:
[Some Text](some-file.md)
becomes
[Some Text](some-file.html)
if some-file.md
is one of the inputs.
Versions of content in other languages should go in two-letter coded sub-directories, e.g.
docs/ja/...
docs/de/...
These will be elided from the main table-of-contents and search indexes. (Currently no language-specific table of contents is built, nor language-specific site search indexes).
Templates are used for HTML (_template.html
), LaTeX (_template.tex
), Notebooks (_template.ipynb)
and F# script outputs (_template.fsx
).
The following substitutions determine the primary (non-styling) content of your site.
For example {{fsdocs-content}}
is replaced with the generated content in each file.
Substitutions are applied when generating content from HTML templates, IPYNB templates, FSX templates.
They are also applied to content apart from Markdown inline code `...`
, Markdown LaTeX and
generated outputs.
See Styling for information about template parameters and styling beyond the default template.
Substitution name |
Generated content |
---|---|
|
|
|
Name of .sln, single .fsproj or containing directory |
|
Main page content |
|
HTML |
|
HTML |
|
First h1 heading in literate file. Generated for API docs |
|
Original literate script or markdown source |
|
Name of original input source, relative to the |
|
Name of original input source, excluding its extensions, relative to the |
|
Generated hidden div elements for tooltips |
|
The websocket script used in watch mode to trigger hot reload |
The following substitutions are extracted from your project files and may or may not be used by the default template:
Substitution name |
Value |
---|---|
|
|
|
|
|
|
|
|
|
|
For the fsdocs
tool, additional substitutions can be specified using --parameters
.
Markdown content can contain cross-references to API Docs. Use inline
markdown code snippets of the special form `cref:T:MyNamespace.MyType`
where T:MyNamespace.MyType
is a method, property or type xml doc sig reference, see API Docs.
This can include any cross-references resolved by fsdocs.
The generated API documentation includes buttons to copy the XML and Markdown forms of API doc references.
For example, within this project,
the text `cref:T:FSharp.Formatting.Markdown.MarkdownParagraph`
resolves to the link MarkdownParagraph
the text `cref:T:System.Console`
resolves to the link Console
the text `cref:M:System.Console.WriteLine`
resolves to the link Console.WriteLine
the text `cref:M:System.Console.WriteLine(System.String)`
resolves to the link Console.WriteLine
the text ``cref:T:FSharp.Control.FSharpAsync`1``
resolves to the link Async
the text `cref:T:FSharp.Control.FSharpAsync`
resolves to the link Async
the text ``cref:T:FSharp.Core.array`1``
resolves to the link array
the text `cref:T:FSharp.Core.OptionModule`
resolves to the link Option
the text ```cref:M:FSharp.Collections.ListModule.Append``1```
resolves to the link ListModule.Append
NOTE: These cases act as tests - if the links above do not work, then that indicates a bug or a change in the external link. Please report it.
Determining xmldoc sig references is not simple. The API doc generated pages come with buttons to copy out the XmlDoc signature.
HTML is generated by default. You can also add a _template.html
. This should contain {{fsdocs-content}}
, {{fsdocs-tooltips}}
and other placeholders. Substitutions are
applied to this template.
If a file _template.html
exists then is used as the template for HTML generation for that directory and all sub-content.
To generate .tex output for each script and markdown file, add a _template.tex
. Substitutions are
applied to this template. The file is either empty of contains {{fsdocs-content}}
as the key where the body
of the document is placed.
To generate .ipynb output for each script and markdown file, add a _template.ipynb
, usually empty. Substitutions are
applied to this template.
To add a mybinder
badge to your generated notebook, ensure you have a Dockerfile
and NuGet.config
in your docs
directory and use text like this:
[](https://mybinder.org/v2/gh/fsprojects/FSharp.Formatting/gh-pages?filepath=literate.ipynb)
To generate .fsx output for each script and markdown file, add a _template.fsx
, usually empty. Substitutions are
applied to this template. It is either empty of contains {{fsdocs-content}}
as the key where the body
of the script is placed.