{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Customization and Styling\n", "\n", "When using `fsdocs`, there are six levels of extra content development and styling.\n", "\n", "0 Don\u0027t do any styling or documentation customization and simply write content. This is by far the simplest option to\n", "maintain.\n", " \n", "\n", "1 Add content such as an `docs/index.md` to customize the front-page content for your generated docs.\n", "You can also add content such as `docs/reference/fslib.md` to give a bespoke landing page\n", "for one of your namespaces, e.g. here assumed to be `namespace FsLib`. This will override any\n", "generated content.\n", " \n", "\n", "2 Customize via Styling Parameters\n", " \n", "\n", "3 Customize via CSS\n", " \n", "\n", "4 Customize via a new template\n", " \n", "\n", "5 Customize by generating your own site using your own code\n", " \n", "\n", "By default `fsdocs` does no styling customization and uses the following defaults. These are the settings used to build\n", "this site.\n", "\n", "* Uses the default template\n", "in [docs/_template.html](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/_template.html)\n", " \n", "\n", "* Uses the default styles\n", "in [docs/content/fsdocs-default.css](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/content/fsdocs-default.css).\n", " \n", "\n", "* Uses no custom styles\n", "in [docs/content/fsdocs-custom.css](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/content/fsdocs-default.css).\n", " \n", "\n", "* Uses no styling parameters except those extracted from the project files.\n", " \n", "\n", "For your project, you don\u0027t need any of these files. However, you can add them if you wish, though if\n", "you adjust them there is no guarantee that your template will continue to work with future versions of F# Formatting.\n", "\n", "## Customizing via Styling Parameters\n", "\n", "The following [content parameters](content.html) are particularly related to visual styling:\n", "\n", "Substitution name | Value (if not overriden by --parameters)\n", ":--- | :---\n", "`fsdocs-authors` | `\u003cAuthors\u003e`\n", "`fsdocs-license-link` | `\u003cFsDocsLicenseLink\u003e`\n", "`fsdocs-logo-src` | `\u003cFsDocsLogoSource\u003e`\n", "`fsdocs-favicon-src` | `\u003cFsDocsFaviconSource\u003e`\n", "`fsdocs-logo-link` | `\u003cFsDocsLogoLink\u003e`\n", "`fsdocs-release-notes-link` | `\u003cFsDocsReleaseNotesLink\u003e` else `\u003cPackageProjectUrl\u003e/blob/master/RELEASE_NOTES.md`\n", "`fsdocs-repository-link` | `\u003cRepositoryUrl\u003e`\n", "`fsdocs-theme` | `\u003cFsDocsTheme\u003e`, must currently be `default`\n", "\n", "\n", "These basic entry-level styling parameters can be set in the project file or `Directory.Build.props`.\n", "For example:\n", "\n", "```xml\n", "\u003cPropertyGroup\u003e\n", " \u003c!-- Example ultra-simple styling and generation settings for FsDocs default template--\u003e\n", " \u003cPackageLicenseUrl\u003ehttps://github.com/foo/bar/blob/master/License.txt\u003c/PackageLicenseUrl\u003e\n", " \u003cPackageProjectUrl\u003ehttps://foo.github.io/bar/\u003c/PackageProjectUrl\u003e\n", " \u003cRepositoryUrl\u003ehttps://github.com/foo/bar/\u003c/RepositoryUrl\u003e\n", " \u003cFsDocsLogoLink\u003ehttps://fsharp.org\u003c/FsDocsLogoLink\u003e\n", " \u003cFsDocsLogoSource\u003eimg/logo.png\u003c/FsDocsLogoSource\u003e\n", " \u003cFsDocsFaviconSource\u003eimg/favicon.ico\u003c/FsDocsFaviconSource\u003e\n", " \u003cFsDocsLicenseLink\u003ehttps://github.com/foo/bar/blob/master/License.txt\u003c/FsDocsLicenseLink\u003e\n", " \u003cFsDocsReleaseNotesLink\u003ehttps://github.com/foo/bar/blob/master/release-notes.md\u003c/FsDocsReleaseNotesLink\u003e\n", " \u003cFsDocsWarnOnMissingDocs\u003etrue\u003c/FsDocsWarnOnMissingDocs\u003e\n", " \u003cFsDocsTheme\u003edefault\u003c/FsDocsTheme\u003e\n", "\u003c/PropertyGroup\u003e\n", "```\n", "\n", "As an example, here is [a page with alternative styling](templates/leftside/styling.html).\n", "\n", "## Customizing via CSS\n", "\n", "You can start styling by creating a file `docs/content/fsdocs-theme.css` and adding entries to it.\n", "It is loaded by the standard template.\n", "\n", "### CSS variables\n", "\n", "The default template is heavily based\n", "on [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). These can easily be\n", "override to customize the look and feel of the default theme.\n", "A full list of the overrideable variables can be\n", "found [here](https://github.com/fsprojects/FSharp.Formatting/blob/main/docs/content/fsdocs-default.css).\n", "\n", "```css\n", ":root {\n", " --text-color: red;\n", "}\n", "\n", "[data-theme=dark] {\n", " --text-color: darkred;\n", "}\n", "```\n", "\n", "Please be aware that the `dark` mode in the default theme is using the same variables.\n", "When you override a variable, it will also be used in `dark` mode unless redefined in a `[data-theme=dark]` CSS query.\n", "\n", "### CSS classes\n", "\n", "The API documentation uses a set of fixed CSS classes:\n", "\n", "CSS class | Corresponding Content\n", ":--- | :---\n", "`.fsdocs-tip` | generated tooltips\n", "`.fsdocs-xmldoc` | generated xmldoc sections\n", "`.fsdocs-member-list` | generated member lists (tables)\n", "`.fsdocs-member-usage` | usage in generated member lists\n", "`.fsdocs-member-tooltip` | tooltips in generated member lists\n", "`.fsdocs-member-xmldoc` | documentation in generated member lists\n", "`.fsdocs-entity-list` | generated entity lists\n", "`.fsdocs-entity-name` | generated entity lists\n", "`.fsdocs-entity-xmldoc` | documentation in generated entity lists\n", "`.fsdocs-exception-list` | generated exception lists\n", "`.fsdocs-summary` | the \u0027summary\u0027 section of an XML doc\n", "`.fsdocs-remarks` | the \u0027remarks\u0027 section of an XML doc\n", "`.fsdocs-params` | the \u0027parameters\u0027 section of an XML doc\n", "`.fsdocs-param` | a \u0027parameter\u0027 section of an XML doc\n", "`.fsdocs-param-name` | a \u0027parameter\u0027 name of an XML doc\n", "`.fsdocs-returns` | the \u0027returns\u0027 section of an XML doc\n", "`.fsdocs-example` | the \u0027example\u0027 section of an XML doc\n", "`.fsdocs-note` | the \u0027notes\u0027 section of an XML doc\n", "`.fsdocs-para` | a paragraph of an XML doc\n", "\n", "\n", "Some generated elements are given specific HTML ids:\n", "\n", "HTML element selector | Content\n", ":--- | :---\n", "`header` | The navigation-bar\n", "`#fsdocs-main-menu` | The main menu on the left side\n", "`#content` | The generated content\n", "`#fsdocs-page-menu` | The sub menu on the right side\n", "`dialog` | The search dialog\n", "`dialog input[type=search]` | The search box\n", "`#fsdocs-logo` | The logo\n", "\n", "\n", "If you write a new theme by CSS styling please contribute it back to FSharp.Formatting.\n", "\n", "## Customizing via a new template\n", "\n", "You can do advanced styling by creating a new template. Add a file `docs/_template.html`, likely starting\n", "with the existing default template.\n", "\n", "\u003e NOTE: To enable hot reload during development with `fsdocs watch` in a custom `_template.html` file,\n", "make sure to add the single line `{{fsdocs-watch-script}}` to your `\u003chead\u003e` tag.\n", "NOTE: There is no guarantee that your template will continue to work with future versions of F# Formatting.\n", "If you do develop a good template please consider contributing it back to F# Formatting.\n", "\u003e \n", "\n", "## Customizing menu items by template\n", "\n", "You can add advanced styling to the sidebar generated menu items by creating a new template for it.\n", "`fsdoc` will look for menu templates in the `--input` folder, which defaults to the docs folder.\n", "\n", "To customize the generated menu-item headers, use file `_menu_template.html` with starting template:\n", "\n", "```html\n", "\u003cli class=\"nav-header\"\u003e\n", " {{fsdocs-menu-header-content}}\n", "\u003c/li\u003e\n", "{{fsdocs-menu-items}}\n", "```\n", "\n", "Similarly, to customize the individual menu item list, use file `_menu-item_template.html` with the starting template:\n", "\n", "```html\n", "\u003cli class=\"nav-item\"\u003e\u003ca href=\"{{fsdocs-menu-item-link}}\" class=\"nav-link\"\u003e{{fsdocs-menu-item-content}}\u003c/a\u003e\u003c/li\u003e\n", "```\n", "\n", "Do note that files must be added before running, or won\u0027t be generated.\n", "In case you want to get a unique identifier for a header or menu item, you can use `{{fsdocs-menu-header-id}}`\n", "and `{{fsdocs-menu-item-id}}`, respectively.\n", "\n", "## Injecting additional html into the default template\n", "\n", "Occasionally, you may find the need to make small customizations to the default template, such as adding a Google\n", "Analytics snippet or including additional style or script tags. To address this scenario, you can create two\n", "files: `_head.html` and/or `_body.html`.\n", "\n", "The content within these files will serve as replacements for the `{{fsdocs-head-extra}}` and `{{fsdocs-body-extra}}`\n", "placeholders, which are utilized in the default template.\n", "\n", "## Customizing by generating your own site using your own code\n", "\n", "The `FSharp.Formatting.ApiDocs` namespace includes a `GenerateModel` that captures\n", "the results of documentation preparation in `ApiDocsModel` and allows you to\n", "generate your own site using your own code.\n", "\n", "\u003e NOTE: The ApiDocsModel API is undergoing change and improvement, and there is no guarantee that your bespoke site\n", "generation will continue to work\n", "with future versions of F# Formatting.\n", "NOTE: The `ApiDocsModel` currently includes some generated HTML with some specific style tags.\n", "In the long term these may be removed from the design of that component.\n", "\u003e \n", "\n" ] } ], "metadata": { "kernelspec": { "display_name": ".NET (F#)", "language": "F#", "name": ".net-fsharp" }, "language_info": { "file_extension": ".fs", "mimetype": "text/x-fsharp", "name": "polyglot-notebook", "pygments_lexer": "fsharp" }, "polyglot_notebook": { "kernelInfo": { "defaultKernelName": "fsharp", "items": [ { "aliases": [], "languageName": "fsharp", "name": "fsharp" } ] } } }, "nbformat": 4, "nbformat_minor": 2 }