Skip to content

Latest commit

 

History

History
221 lines (156 loc) · 8.64 KB

README.md

File metadata and controls

221 lines (156 loc) · 8.64 KB
Raw

Website

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

The website is built using Docusaurus, a modern static website generator.

Dependency installation

The Fluid Framework repository uses pnpm for dependency management. If you don't have pnpm installed, you will need to do so first.

pnpm i

Local Development

There are two options for local testing.

build:generate-content and start

The easiest way to get started testing the website is to leverage Docusaurus's start functionality. This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Before you can use this, you'll need to ensure our API documentation has been built. So start by running:

npm run build:generate-content

Then, run:

npm start

Limitations

The following functionality will not work in this mode. Instead, you will need to build and serve

Search

Our current offline search implementation does not work in this mode. It requires running a full build to run its indexing. To test search, you will need to use the build and serve workflow instead.

build and serve

The second option, which is substantially slower, leverages the same build that our build pipelines use to generate our production site. First, run:

npm run build

This command generates static content into the build directory and can be served using any static contents hosting service. This includes the generation of API documentation contents.

To just run content generation steps, run build:generate-content. To just build the static site (without rebuilding the API documentation), run build:site.

Then, run:

npm run serve

Note: the Docusaurus build is fairly slow. If you don't need to test search, it is recommended to run npm start instead. This is faster, and will watch for content changes and update automatically. You will still need to build the API documentation first.

Local API docs build

To include repo-local API documentation when building the site locally, you will first need to do the following:

  1. Build the code from the root of the repo.
  2. Create a .env file in this directory with the following contents: 
    LOCAL_API_DOCS=true

So long as the LOCAL_API_DOCS environment variable is set to true, local API documentation will be included when building the site. To remove the local API docs, simply remove the above variable or set it to false, npm run clean and rebuild as needed.

Writing site documentation

For details about authoring documentation content in Docusaurus, see here.

File organization

|--- docs (Current version documentation)
|--- versioned_docs (previous and future version documentation)
|    |---version-x (version *x* documentation)
|    |---version-local (special directory in which repo-local API docs are generated and can be previewed when building the site locally)
|--- src
|    |--- components (React components available to other site documents, pages, and components)
|    |--- css (CSS modules available to other site documents, pages, and components)
|    |--- pages (Unversioned site contents)
|    |--- theme (Theme component / page overrides)

MDX

MDX syntax (supported by Docusaurus) is powerful. But there is a subset of standard Markdown syntax that is not supported. For example, any HTML-like syntax will always be treated as JSX syntax, so standard embedded HTML patterns don't work. Most of the time, this isn't an issue, since substituting JSX syntax is generally fine. With some exceptions.

Leveraging React components

For an overview of how to leverage React components in MDX documentation, see here.

Adding React components

React components should be saved under src/components/.... They can be imported in other components, pages, and documents via @site/src/components/....

Comments

A common pattern for adding inline comments in .md files looks like:

<!-- I am a comment -->

The replacement syntax to use in .mdx files would be:

{/* I am a comment */}

(just like you would do in a JSX context!)

Mermaid

Docusaurus has built-in support for mermaid diagrams. We recommend leveraging these when possible over alternatives (ascii art, binary image files, SVG, etc.).

Rationale:

  • Docusaurus will ensure consistent styling
  • Non-binary source, directly in the document.

For more details about leveraging Mermaid diagrams in Docusaurus, see here.

Best practices

Markdown

Links
  • Don't include file extensions in links. E.g., prefer [foo](./foo) over [foo](./foo.md).
    • Rationale: more portable (if a document changes from .md to .mdx, for example, links will not need to be updated).

Assets

Images

When adding image assets for use in the website, please follow the instructions outlined here. Namely, avoid adding binary files like images to the GitHub repo. Instead, upload them to our Azure blob storage, and reference by URL.

Images may only be uploaded by Microsoft Fluid team members. If you do not have the appropriate permissions, but would like to contribute to our documentation, please reach out to us here.

Scripts

The following npm scripts are supported in this directory:

Script Description
build Build everything: the API documentation, the website, the tests, etc.
prebuild:api-documentation Temporary workaround for AB#24394. Cleans up existing generated API documentation before generating new content.
build:api-documentation Download API model artifacts and generate API documentation.
prebuild:docusaurus Runs pre-site build metadata generation.
build:docusaurus Build the website with Docusaurus.
build:generate-content Generate site content. Includes API documentation, as well as content generated / embedded by markdown-magic.
build:markdown-magic Run markdown-magic to generate / embed contents in Markdown files.
build:site Build the site, including API documentation.
build:test TSC build of the test code as a sanity check.
check-links Run link validation on the website. Requires the website to be running locally, either via start or serve.
ci:check-links check-links variant for CI. Serves the site before running checks.
clean Clean up generated artifacts (build output, etc.).
clean:api-documentation Clean up generate API documentation content.
clean:doc-models Clean up downloaded API model artifacts.
clean:docusaurus Run Docusaurus's "clean".
clean:test Clean up generated test output
clean:versions-json Clean up generated versions.json file.
download-doc-models Download API model artifacts published from our release branches.
eslint Run eslint.
eslint:fix Run eslint with auto-fix enabled.
format Fix formatting issues with prettier.
generate-api-documentation Generate API documentation from downloaded API model artifacts.
generate-versions dotenv -- node ./infra/generate-versions.mjs
lint Check for linter violations.
lint:fix Auto-fix linter violations.
preinstall Ensure developer is using pnpm.
prettier Check for formatting issues with prettier.
prettier:fix Fix formatting issues with prettier.
rebuild Clean up existing generated artifacts and re-run the build.
serve Serves the built website using Docusaurus.
serve-with-azure-emulation Serves the built website using Docusaurus, including Azure service emulation for our Azure functions.
prestart Runs pre-site build metadata generation.
start Runs the website in watch mode with Docusaurus.
pretest Install necessary playwright dependencies before running tests.
test Run tests using playwright