Skip to content

Latest commit

 

History

History
234 lines (175 loc) · 7.45 KB

README.md

File metadata and controls

234 lines (175 loc) · 7.45 KB
Raw

fluidframework-docs

This is the code and content for https://fluidframework.com.

Previewing the documentation site 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.

API documentation and Playground

The steps above won't include API documentation (the TSDoc JSON files) or the Playground by default. You can download the latest API docs and Playground files with the download script.

npm run download

Note that this script will overwrite any locally built API docs.

Building the documentation

Run the build script to build the site. The output will be in the public/ folder.

npm run build

Drafts and future content

By default the build script won't build content with a future published date or draft flag. To build this content, use the --buildDrafts and --buildFuture flags.

npm run build -- --buildDrafts --buildFuture

Content with a future published date won't automatically publish on that date. You'll need to run the build process.

API documentation

Building API documentation locally requires an extra step to generate the content from the source.

From the root of the repository:

npm install
npm run build:fast -- --symlink:full --install --all
npm run build:fast -- -s build -s build:docs --nolint --all

You can then build or preview the docs using the steps described earlier.

Note that this will leave the fluid-build tool in full-symlink mode. To return to the default isolated mode (e.g. for typical development) run:

npm run build:fast -- --symlink

Understanding the API documentation build pipeline

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:

  1. Root: build:fast
    1. Compile the code, generating TypeScript definitions, etc.
  2. Root: build:docs
    1. Run the @microsoft/api-extractor (using Lerna) 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.
    2. The JSON is also copied from each package up to a shared _api-extractor-temp directory under the repository root.
  3. /docs: build
    1. Run markdown-magic to update some shared content in the source Markdown files.
    2. Run the @mattetti/api-extractor tool to transform the JSON format into Markdown. The generated Markdown is placed at /docs/content/apis. We maintain this fork of @microsoft/api-extractor here.
    3. Run ditaa to build some of the diagrams in the site.
    4. Run hugo to build the site itself. The generated output is placed at /docs/public/apis.
  4. /docs: start
    1. Run the hugo server to host the site at http://localhost:1313.

To investigate incorrect output, you can check the intermediate outputs (JSON, Markdown, HTML) at these locations to narrow down where the error is occurring.

Creating new content

You need to generate new content manually by creating new files by hand or by generating them using the hugo command as shown below:

Static doc

npm run hugo -- new docs/concepts/flux-capacitor.md

Blog post

npm run hugo -- new posts/fluid-everywhere.md

Content guidelines

Try to use Markdown as much as possible. You can embed HTML in Markdown, but we recommended sticking to Markdown and shortcodes/partials.

Menus

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).

Main menu (top menu)

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

Docs menu

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).

API menu

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 being generated with metadata which allows the template to link pages and load the right information.

Table of Contents

Some template pages include a TOC of the page. This is generated on the fly by reading the headers.

Social action

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.

Shortcodes

Shortcodes are custom functions that can be called from within the Markdown to insert specific content.

Working on the template

The site theme/template lives in themes/thxvscode.

Scripts

Script Description
build Build the site; outputs to public/ by default.
build:api-documenter Convert API JSON into Markdown.
build:api-documenter:default ---
build:api-documenter:win32 ---
build:diagrams Generate the diagram images using ditaa.
build:md-magic Updates generated content in Markdown files.
clean Remove all generated files.
copyfiles copyfiles _replacements/ content/
ditaa Run the local copy of ditaa.
ditaa:default ---
ditaa:win32 ---
download Download and extract the API JSON and Playground files locally.
download:api Download and extract the API JSON files locally.
download:playground Download and extract the Playground files locally.
hugo Run the local copy of Hugo.
hugo:default ---
hugo:win32 ---
install:ditaa Install ditaa to generate diagrams unless it already exists.
install:ditaa:default ---
install:ditaa:force Install ditaa to generate diagrams.
install:ditaa:win32 ---
install:hugo Install Hugo unless it already exists.
install:hugo:default ---
install:hugo:force Install the version of Hugo used by the documentation.
install:hugo:win32 ---
postinstall ---
start Start a local webserver to preview the built site on http://localhost:1313
start:default ---
start:win32 ---