{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ ] } , { "cell_type": "code", "metadata": { "dotnet_interactive": { "language": "fsharp" }, "polyglot_notebook": { "kernelName": "fsharp" } }, "execution_count": null, "outputs": [], "source": [ "#r \"nuget: FSharp.Formatting,1.0.0\"\n" ] } , { "cell_type": "markdown", "metadata": {}, "source": [ "[![Binder](img/badge-binder.svg)](https://mybinder.org/v2/gh/fsprojects/fsharp.formatting/gh-pages?filepath=content.ipynb)\u0026emsp;\n", "[![Script](img/badge-script.svg)](https://fsprojects.github.io/FSharp.Formatting//content.fsx)\u0026emsp;\n", "[![Notebook](img/badge-notebook.svg)](https://fsprojects.github.io/FSharp.Formatting//content.ipynb)\n", "\n", "# Creating Content\n", "\n", "The [\"fsdocs\" tool](commandline.html) allows documentation for a site to be built\n", "from content in a `docs` directory. The expected structure for a `docs` directory is\n", "\n", " [lang=text]\n", " docs/**/*.md -- markdown with embedded code, converted to html and optionally tex/ipynb\n", " docs/**/*.fsx -- fsx scripts converted to html and optionally tex/ipynb\n", " docs/**/* -- other content, copied over\n", " docs/**/_template.html -- optional template, specifies the HTML template for this directory and its contents\n", " docs/**/_template.tex -- optionally indicates Latex files should be generated\n", " docs/**/_template.ipynb -- optionally indicates F# ipynb files should be generated\n", " docs/**/_template.fsx -- optionally indicates F# fsx files should be generated (even from markdown)\n", " docs/reference/_template.html -- optionally specifies the default template for reference docs\n", "\n", "Processing is by these two commands:\n", "\n", " dotnet fsdocs build\n", " dotnet fsdocs watch\n", "\n", "The output goes in `output/` by default. Processing is recursive, making this a form of static site generation.\n", "\n", "## Literate Scripts and Markdown Content\n", "\n", "The input directory may contain [literate scripts](literate.html) and markdown content.\n", "\n", "## Other Content\n", "\n", "Content that is not `*.fsx` or `*.md` is copied across.\n", "\n", "## Default Styling Content\n", "\n", "By default additional content such as `fsdocs-search.js`, `fsdocs-tips.js` and `fsdocs-default.css` are included in the\n", "the `content` directory of the output. This can be suppressed with `--nodefaultcontent` or by having your own\n", "copy of this content in your `content` directory.\n", "\n", "## Ignored Content\n", "\n", "Any file or directory beginning with `.` is ignored.\n", "\n", "## Front matter\n", "\n", "Each content file can have optional frontmatter. This determines the navigation bar title, categorization ordering and meta tags.\n", "\n", "For markdown, the format is:\n", "\n", "```\n", "---\n", "title: Some Title\n", "category: Some Category\n", "categoryindex: 2\n", "index: 3\n", "description: Some description\n", "keywords: tag1, tag2, tag3\n", "---\n", "```\n", "For F# scripts the frontmatter is in this form:\n", "\n", " (**\n", " ---\n", " title: A Literate Script\n", " category: Examples\n", " categoryindex: 2\n", " index: 1\n", " description: Some description\n", " keywords: tag1, tag2, tag3\n", " ---\n", " *)\n", "\n", "All entries are optional.\n", "The `categoryindex` determines the ordering of categories.\n", "The `index` determines the ordering of within each category.\n", "The `title` is used in the navigation bar instead of any title inferred from the document.\n", "The `description` is used in `\u003cmeta name=\"description\"` as part of the `{{fsdocs-meta-tags}}` substitution.\n", "The `keywords` are also used in a meta tag as part of `{{fsdocs-meta-tags}}`. Separate them using a `,`.\n", "\n", "## Link Translation for Inputs\n", "\n", "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:\n", "\n", " [Some Text](some-file.md)\n", "\n", "becomes\n", "\n", " [Some Text](some-file.html)\n", "\n", "if `some-file.md` is one of the inputs.\n", "\n", "## Multi-language Content\n", "\n", "Versions of content in other languages should go in two-letter coded sub-directories, e.g.\n", "\n", " docs/ja/...\n", " docs/de/...\n", "\n", "These will be elided from the main table-of-contents and search indexes. (Currently no language-specific\n", "table of contents is built, nor language-specific site search indexes).\n", "\n", "## Templates and Substitutions\n", "\n", "Templates are used for HTML (`_template.html`), LaTeX (`_template.tex`), Notebooks (`_template.ipynb)`\n", "and F# script outputs (`_template.fsx`).\n", "\n", "The following substitutions determine the primary (non-styling) content of your site.\n", "For example `{{fsdocs-content}}` is replaced with the generated content in each file.\n", "\n", "Substitutions are applied when generating content from HTML templates, IPYNB templates, FSX templates.\n", "They are also applied to content apart from Markdown inline code ``...``, Markdown LaTeX and\n", "generated outputs.\n", "\n", "See [Styling](styling.html) for information about template parameters and styling beyond the default template.\n", "\n", "Substitution name | Generated content\n", ":--- | :---\n", "`root` | `\u003cPackageProjectUrl\u003e` else `/` followed by `fsdocs-collection-name`\n", "`fsdocs-collection-name` | Name of .sln, single .fsproj or containing directory\n", "`fsdocs-content` | Main page content\n", "`fsdocs-list-of-namespaces` | HTML `\u003cli\u003e` list of namespaces with links\n", "`fsdocs-list-of-documents` | HTML `\u003cli\u003e` list of documents with titles and links\n", "`fsdocs-page-title` | First h1 heading in literate file. Generated for API docs\n", "`fsdocs-source` | Original literate script or markdown source\n", "`fsdocs-source-filename` | Name of original input source, relative to the `docs` root\n", "`fsdocs-source-basename` | Name of original input source, excluding its extensions, relative to the `docs` root\n", "`fsdocs-tooltips` | Generated hidden div elements for tooltips\n", "`fsdocs-watch-script` | The websocket script used in watch mode to trigger hot reload\n", "`fsdocs-previous-page-link` | A relative link to the previous page based on the frontmatter index data\n", "`fsdocs-next-page-link` | A relative link to the next page based on the frontmatter index data\n", "`fsdocs-head-extra` | Additional html content loaded from the `_head.html` file if present in the `--input` folder\n", "`fsdocs-body-extra` | Additional html content loaded from the `_body.html` file if present in the `--input` folder\n", "`fsdocs-body-class` | A css class value to help distinguish between `content` and `api-docs`\n", "`fsdocs-meta-tags` | A set of additional HTML meta tags, present when description and/or keywords are present in the frontmatter\n", "\n", "\n", "The following substitutions are extracted from your project files and may or may not be used by the default\n", "template:\n", "\n", "Substitution name | Value\n", ":--- | :---\n", "`fsdocs-copyright` | `\u003cCopyright\u003e`\n", "`fsdocs-package-project-url` | `\u003cPackageProjectUrl\u003e`\n", "`fsdocs-package-license-expression` | `\u003cPackageLicenseExpression\u003e`\n", "`fsdocs-package-tags` | `\u003cPackageTags\u003e`\n", "`fsdocs-package-version` | `\u003cVersion\u003e`\n", "\n", "\n", "For the `fsdocs` tool, additional substitutions can be specified using `--parameters`.\n", "\n", "## Cross References to API Docs\n", "\n", "Markdown content can contain cross-references to API Docs. Use inline\n", "markdown code snippets of the special form ``cref:T:MyNamespace.MyType`` where `T:MyNamespace.MyType`\n", "is a method, property or type xml doc sig reference, see [API Docs](apidocs.html).\n", "This can include any cross-references resolved by fsdocs.\n", "\n", "The generated API documentation includes buttons to copy the XML and Markdown forms of API doc references.\n", "\n", "For example, within this project,\n", "\n", "* the text ``cref:T:FSharp.Formatting.Markdown.MarkdownParagraph`` resolves to the link [MarkdownParagraph](https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-markdown-markdownparagraph.html)\n", " \n", "\n", "* the text ``cref:T:System.Console`` resolves to the link [Console](https://learn.microsoft.com/dotnet/api/system.console)\n", " \n", "\n", "* the text ``cref:M:System.Console.WriteLine`` resolves to the link [Console.WriteLine](https://learn.microsoft.com/dotnet/api/system.console.writeline)\n", " \n", "\n", "* the text ``cref:M:System.Console.WriteLine(System.String)`` resolves to the link [Console.WriteLine](https://learn.microsoft.com/dotnet/api/system.console.writeline)\n", " \n", "\n", "* the text ```cref:T:FSharp.Control.FSharpAsync`1``` resolves to the link [Async](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync-1)\n", " \n", "\n", "* the text ``cref:T:FSharp.Control.FSharpAsync`` resolves to the link [Async](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync)\n", " \n", "\n", "* the text ```cref:T:FSharp.Core.array`1``` resolves to the link [array](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-core-array-1)\n", " \n", "\n", "* the text ``cref:T:FSharp.Core.OptionModule`` resolves to the link [Option](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-core-optionmodule)\n", " \n", "\n", "* the text ````cref:M:FSharp.Collections.ListModule.Append``1```` resolves to the link [ListModule.Append](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-collections-listmodule#Append)\n", " \n", "\n", "\u003e NOTE: These cases act as tests - if the links above do not work, then that indicates a bug or a change in the\n", "external link. [Please report it](https://github.com/fsprojects/FSharp.Formatting/issues/new).\n", "\u003e \n", "\n", "Determining xmldoc sig references is not simple. The API doc generated pages come with\n", "buttons to copy out the XmlDoc signature.\n", "\n", "## Generating HTML Output\n", "\n", "HTML is generated by default. You can also add a `_template.html`. This should contain `{{fsdocs-content}}`, `{{fsdocs-tooltips}}`\n", "and other placeholders. Substitutions are\n", "applied to this template.\n", "If a file `_template.html` exists then is used as the template for HTML generation for that directory and all sub-content.\n", "\n", "## Generating LaTeX output\n", "\n", "To generate .tex output for each script and markdown file, add a `_template.tex`. Substitutions are\n", "applied to this template. The file is either empty of contains `{{fsdocs-content}}` as the key where the body\n", "of the document is placed.\n", "\n", "## Generating iPython Notebook output\n", "\n", "To generate .ipynb output for each script and markdown file, add a `_template.ipynb`, usually empty. Substitutions are\n", "applied to this template.\n", "\n", "To add a `mybinder` badge to your generated notebook, ensure you have a `Dockerfile` and `NuGet.config`\n", "in your `docs` directory and use text like this:\n", "\n", " [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/fsprojects/FSharp.Formatting/gh-pages?filepath=literate.ipynb)\n", "\n", "## Generating Script outputs\n", "\n", "To generate .fsx output for each script and markdown file, add a `_template.fsx`, usually empty. Substitutions are\n", "applied to this template. It is either empty of contains `{{fsdocs-content}}` as the key where the body\n", "of the script is placed.\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 }