When using fsdocs
, there are six levels of extra content development and styling.
Add content such as an docs/index.md
to customize the front-page content for your generated docs.
You can also add content such as docs/reference/fslib.md
to give a bespoke landing page
for one of your namespaces, e.g. here assumed to be namespace FsLib
. This will override any
generated content.
By default fsdocs
does no styling customization and uses the following defaults. These are the settings used to build this site.
Uses the default template in docs/_template.html
Uses the default styles in docs/content/fsdocs-default.css.
Uses no custom styles in docs/content/fsdocs-custom.css.
For your project, you don't need any of these files. However you can add them if you wish, though if you adjust them there is no guarantee that your template will continue to work with future versions of F# Formatting.
The following content parameters are particularly related to visual styling:
Substitution name |
Value (if not overriden by --parameters) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
These basic entry-level styling parameters can be set in the project file or Directory.Build.props
.
For example:
|
As an example, here is a page with fsdocs-navbar-position
set to fixed-right
.
You can start styling by creating a file docs/content/fsdocs-custom.css
and adding entries to it. It is loaded by
the standard template. The CSS classes of generated content are:
CSS class |
Corresponding Content |
---|---|
|
generated tooltips |
|
generated xmldoc sections |
|
generated member lists (tables) |
|
usage in generated member lists |
|
tooltips in generated member lists |
|
documentation in generated member lists |
|
generated entity lists |
|
generated entity lists |
|
documentation in generated entity lists |
|
generated exception lists |
|
the 'summary' section of an XML doc |
|
the 'remarks' section of an XML doc |
|
the 'parameters' section of an XML doc |
|
a 'parameter' section of an XML doc |
|
a 'parameter' name of an XML doc |
|
the 'returns' section of an XML doc |
|
the 'example' section of an XML doc |
|
the 'notes' section of an XML doc |
|
a paragraph of an XML doc |
Some generated elements are given specific HTML ids:
HTML Element Id |
Content |
---|---|
|
The generated content |
|
The search box |
|
The logo |
|
The navigation-bar |
If you write a new theme by CSS styling please contribute it back to FSharp.Formatting.
You can do advanced styling by creating a new template. Add a file docs/_template.html
, likely starting
with the existing default template.
NOTE: To enable hot reload during development with
fsdocs watch
in a custom_template.html
file, make sure to add the single line{{fsdocs-watch-script}}
to your<head>
tag. NOTE: There is no guarantee that your template will continue to work with future versions of F# Formatting. If you do develop a good template please consider contributing it back to F# Formatting.
You can add advanced styling to the sidebar generated menu items by creating a new template for it.
fsdoc
will look for menu templates in the --input
folder which defaults to the docs folder.
To customize the generated menu-item headers, use file _menu_template.html
with starting template:
|
Similarly, to customize the individual menu item list, use file _menu-item_template.html
with starting template:
|
Do note that files need to be added prior running or won't be generated.
In case you want to get a unique identifier for a header or menu item, you can use {{fsdocs-menu-header-id}}
and {{fsdocs-menu-item-id}}
, respectively.
The FSharp.Formatting.ApiDocs
namespace includes a GenerateModel
that captures
the results of documentation preparation in ApiDocsModel
and allows you to
generate your own site using your own code.
NOTE: The ApiDocsModel API is undergoing change and improvement and there is no guarantee that your bespoke site generation will continue to work with future versions of F# Formatting. NOTE: The
ApiDocsModel
currently includes some generated HTML with some specific style tags. In the long term these may be removed from the design of that component.