This is the code and content for https://fluidframework.com.
The site is generated using Hugo.
To quickly get started previewing the website's contents locally, open the docs folder in a terminal and install the dependencies using npm.
cd docs
npm install
Then, start the server.
npm start
Open http://localhost:1313 to preview the site.
The steps above won't include API documentation (the TSDoc JSON files) or the Playground by default.
To include generated API documentation in your local preview, you can run a complete build from the repo root.
Then run the build:api
script from this directory.
npm run build:api
Alternatively, you can skip the complete repo build by downloading the latest API docs and Playground files with the download
script.
npm run download
Note that the
download
script will overwrite any locally built API docs.
To build the website and run other repo-wide documentation generation, run the build
script.
The output will be in the public/
folder.
npm run build
To strictly build the website (and omit documentation generation steps elsewhere in the repo), you can instead run the build:website
script.
npm run build:website
To strictly run documentation generation for the remainder of the repo (everything not under /docs
), you can instead run the build:repo-docs
script.
npm run build:repo-docs
Work-in-progress documents that are not ready for public consumption can be safely added by annotatting them with the draft
flag in their frontmatter.
Example:
---
title: "Foo"
draft: true
---
Such documents will be disregarded by the build (by default) and will not be published.
Drafts are a good option for making incremental progress on a document via pull requests before being ready to actually publish for the world to see.
For more documentation on this Hugo feature, see here.
As noted above, the build
script won't build draft
content.
To build this content and preview it locally, you can run the build with the --buildDrafts
flag.
npm run build -- --buildDrafts
Hugo also supports creating content to be published at some future, pre-defined date and time.
Note: we currently do not have a workflow for pre-publishing website content. These docs are here as a placeholder until we enable such functionality.
For more documentation on this Hugo feature, see here.
To build content and preview future content locally, you can run the build with the --buildFuture
flag.
npm run build -- --buildFuture
Building API documentation locally requires an extra step to generate the content from the source.
To build everything, you can use fluid-build from the repository root, and specify -s build:docs
.
E.g.
fluid-build -s build -s build:docs --all
If you encounter problems updating or building the API docs, it can be helpful to have a high-level understanding of how it gets built. The steps are as follows:
- Root:
build:fast
- Compile the code, generating TypeScript definitions, etc.
- Root:
build:docs
- Run API-Extractor in each package to extract documentation info in a
JSON
format.- The output is placed in a folder
_api-extractor-temp
in each package's directory.
- The output is placed in a folder
- The
JSON
is also copied from each package up to a shared_api-extractor-temp
directory under the repository root.
- Run API-Extractor in each package to extract documentation info in a
/docs
:build
- Run markdown-magic to update some shared content in the source
Markdown
files (both in thedocs
directory and throughout the rest of the repo). - Run api-documenter to transform
JSON
-formatted API reports generated byAPI-Extractor
intoMarkdown
-formatted documentation.- The generated
Markdown
is placed under/docs/content/apis
.
- The generated
- Run
Hugo
to build the site itself. The generated output is placed at/docs/public/apis
.
- Run markdown-magic to update some shared content in the source
/docs
:start
- Run the
Hugo
server to host the site at http://localhost:1313.
- Run the
To investigate incorrect output, you can check the intermediate outputs (JSON
, Markdown
, HTML
) at these locations to narrow down where the error is occurring.
The following are tools used by this package.
We use a tool called markdown-magic to generate and embed contents in Markdown
content throughout our repo.
This includes website contents, package READMEs, etc.
This tool is highly extensible, and new functionality can be added pretty simply by modifying ./md-magic.config.js
.
We use an internal tool, @fluid-tools/api-markdown-documenter, to process API reports generated by API Extractor
and generate Markdown
-formatted API documentation.
The invocation script for this tool is ./api-markdown-documenter.js
.
In order to create new documentation content, you will need to either generate new content manually by creating new files, or by generating them using the hugo
command as shown below:
- Static
Markdown
document:npm run hugo -- new docs/concepts/flux-capacitor.md
- Blog post:
npm run hugo -- new posts/fluid-everywhere.md
Try to use Markdown
as much as possible.
You can embed HTML
in Markdown
, but we recommended sticking to Markdown
and shortcodes/partials.
Menus are mainly managed in config.yml
but depending on the menu, the sub headers might be driven by the content in the repo (pages or data files).
The top menu is configured in the config.yml
file and can look like this:
menu:
main:
- name: "Docs"
url: "/docs/"
weight: -90
- name: "API"
url: "/apis/"
weight: -80
- name: "Blog"
url: "/posts/"
weight: -50
The docs menu is implemented in the theme's _partial/docNav.html
and is using the config.yml
to find the headers and then uses the area attribute of each sub section (sub folders in the content folder) to populate the pages displayed in the menu.
Here is an example of what config.yml
could contain:
menu:
docs:
- identifier: "get-started"
name: "Get Started"
weight: -500
- identifier: "concepts"
name: "Main concepts"
weight: -300
- identifier: "faq"
name: "FAQ"
url: "/docs/faq/"
weight: -100
Those are headers for the Docs menu, they each have a name
field which is used to display the header in the menu.
They also have an identifier
key which is used to map content with matching area
field (often set to cascade within a sub folder).
Finally, you have a weight
field that is used to decide the positioning of each item in the menu.
The lighter an item is, the higher it goes in order (closer to the top).
The API menu is a bit more complex since it's driven by content.
The left menu (API overview) is a list of grouped packages, the grouping comes from a yaml file in the data
folder (packages.yaml
).
The API documentation is generated with metadata which allows the template to link pages and load the right information.
Some template pages include a table of contents (TOC) of the page. This is generated automatically by reading the headers.
There is a menu with actions such as tweeting the page, subscribing to the feed, asking questions etc... This is driven from the theme and the information for the accounts should be in the config.
Please refer to the following guidelines when writing new Markdown
content for the website.
Remember that we prefer
Markdown
overHTML
contents whenever possible, but you may embedHTML
in yourMarkdown
contents as needed.
Standard Markdown links are supported in our Hugo
ecosystem.
When linking to external webpages, this is the syntax we recommend.
When linking to other documents on the website, however, we recommend either using the built-in relref
shortcode, or one of our custom shortcode templates.
These are designed to reduce boilerplate and be more tolerant to future changes to the website.
Shortcodes are custom functions that can be called from within the Markdown
or HTML
to insert specific content.
Hugo
comes with a large suite of built-in shortcode templates that can be used when writing documentation.
The complete list can be found here.
We will call out a few here in more detail because we recommend using them, and expect them to be used frequently.
The relref
shortcode is useful for linking to other pages on the website.
It accepts a file-name / partial file-path (and optional heading ID), and generates a relative path link to that document.
Note: we recommend using
relref
overref
, asref
will generate an absolute url link, and won't work nicely when previewing the site locally.
Using relref
is a great option when adding links between documents on the website, as it is more tolerant of file-wise changes made over time.
Markdown
like the following:
https://fluidframework.com/docs/build/containers/
For more details, see [Creating a container]({{< relref "containers.md#creating-a-container" >}}).
will generate something like:
For more details, see <a href="/docs/build/containers/#creating-a-container">Creating a container</a>.
We have a series of premade shortcode templates that we use throughout our website content.
These can be found under layouts/shortcodes
.
When linking to the API docs for a class, interface, etc., we recommend using our apiref
shortcode, rather than writing a manual link.
This has a few of benefits:
- The shortcode is configured to understand our API documentation configuration, so it is better equipped to deal with file paths, etc.
- The generated link is formatted as a
<code>
block automatically. - It reduces boilerplate.
The shortcode accepts a single argument: the name of the API item being referenced.
Note that this will only work correctly for
package
,class
,interface
, andnamespace
/module
items, as they are the only items for which individual.md
files are generated for. Contents likeparamters
,methods
, etc. are rendered as sub-headings in their parent item's documents.
This shortcode can be found in layouts/shortcodes/apiref.html
.
Markdown
like the following:
The {{< apiref "FluidContainer" "class" >}} class can be used to...
will generate something like:
The <a href="{{ relref /docs/apis/fluid-static/fluidcontainer-class.md }}"><code>FluidContainer</code></a> class can be used to...
The site theme/template lives in themes/thxvscode
.
The following npm scripts are supported in this directory:
Script | Description |
---|---|
build |
Build the site; outputs to public/ by default. |
build:api |
npm run build:api-rollup && npm run build:api-documentation |
build:api-documentation |
Convert package API reports (.api.json files) into Markdown. |
build:api-rollup |
Runs rollup-api-json.js to produce rolled-up API data. See the script for more details. |
build:md-magic |
Updates generated content in Markdown files. |
build:md-magic:code |
node markdown-magic-code.js |
build:md-magic:website |
node markdown-magic-website.js |
build:repo-docs |
npm run build:md-magic:code |
build:website |
npm run build:api-rollup && npm run build:md-magic:website && npm run build:api-documentation && npm run hugo |
ci:build |
npm run download && npm run build |
clean |
Remove all generated files. |
download |
Download and extract the API JSON and Playground files locally. |
download:api |
Download and extract the API JSON files locally. |
hugo |
Run the local copy of Hugo. |
linkcheck |
npm run linkcheck:fast -- --external |
linkcheck:fast |
linkcheck http://localhost:1313 --skip-file skipped-urls.txt |
lint |
markdownlint-cli2 |
lint:fix |
markdownlint-cli2-fix |
start |
Start a local webserver to preview the built site on http://localhost:1313 |