Standard Notes Documentation

Introduction

This website is built using Docusaurus 2, a modern static website generator. You can read the about the full features of Docusaurus on the official Docusaurus documentation.

Docusaurus is a static site generator, which means that the production version of the website contains only static assets such as HTML, CSS, and JavaScript, and the entire website is rendered before it is loaded onto the production server. The website can then be served on static hosting service such as GitHub Pages.

Each push to the main branch of the repository will automatically deploy the website to GitHub Pages. The configuration for this continuous deployment is located at ./.github/workflows/deploy.yml. The URL for the website is located at static/CNAME.

Files

.gitignore - This specifies which files Git should ignore when committing and pushing to remote repositories.
.prettierrc - This specifies the rules for Prettier, a code formattter
docusaurus.config.js - This is the configuration file for Docusaurus. You can manage the links in the header and footer, and site metadata here. A more in-depth introduction to this configuration file is available on the Docusaurus website and full documentation for the API is here.
package.json - This specifies the dependencies for the website and the commands that you can run with yarn.
sidebars.js - This specifies the sidebars for your documentation. The full documentation for this file is available on the Docusaurus website.
yarn.lock - This specifies the full dependencies for the website including the dependencies of the dependencies listed in package.json. Do not edit this file directly. Edit package.json instead, then run yarn install as described below.

The .md files in the docs directory are the docs. See the Docusaurus website for the full documentation on how to create docs and to manage the metadata.

The custom.scss file in src/css defines global styles as described on the Docusaurus website.

The .js files in src/pages are Docusaurus pages that serve as redirects. You can also set up redirects using the plugin-client-redirects plugin in docusaurus.config.js

Development

A full list of the commands for the Docusaurus CLI is available at the Docusaurus website.

Prerequisites

To get started with developing this website, you need to install the following technologies on your device

Node.js version >= 12.13.0 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed
Yarn version >= 1.5 (which can be checked by running yarn --version). Yarn is a performant package manager for JavaScript and replaces the npm client. It is not strictly necessary, but highly encouraged because we use it.

We also recommend that you download the following technologies:

Visual Studio Code - A text editor to edit the source files of your editor
Git - A tool for managing different versions of the website

Installation

yarn install

This command reads the dependencies from the package.json file, updates the dependencies of those dependencies in

Start

yarn start

This command starts a local development server at port 3002, opens up a browser window, and loads localhost:3002. Most changes are reflected live without having to restart the server. To close this, press Ctrl/Cmd+C.

Build

yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Serve

yarn serve

Serve your built website locally through port 3000. Open localhost:3000 to test the production build of your website before committing it to Git.

Deployment

GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

We use GitHub Pages to host our website. This command is a convenient way to build the website and push to the gh-pages branch.

To use this command, you need to set up SSH and make sure that your git remote URL uses SSH. To check your git remote, run git remote -v. The console should output something like this:

origin  git@github.com:standardnotes/docs.git (fetch)
origin  git@github.com:standardnotes/docs.git (push)

If the part after origin begins with https:// instead of git@, run this:

git remote set-url origin git@github.com:standardnotes/docs.git

Creating a new documentation file

Try to name the new documentation file using the desired URL path for that file. The default id is the name of the file before the .md, so naming the documentation files this way allows linking between docs with path names (e.g., ./self-hosting/getting-started.md).
Copy the contents of docs/template into your new documentation file. The template contains standard keywords and a link to the standard meta image.
In VSCode, you can easily change Template to be desired word or phrase by right-clicking the word Template then clicking "Change all occurrences".
Finish writing the new documentation.
Add the id to sidebars.js.
Run yarn build before committing and make sure that the build process is successful.

When possible, use path names when linking between docs (see #1 above). This improves the editing experience because we can easily switch between docs in VSCode by pressing Ctrl/Cmd and clicking the links. Docusaurus will automatically remove the .md in the path of the doc. If you are developing and the .md does not update immediately, shut down your development server and restart it.

Style Guide

Please follow the following writing style guide. These guidelines are open for discussion and are subject to change as we see fit, but we should be consistent about them:

Add periods to complete sentences in lists.
Use "sign in to" instead of "sign into" to be consistent with the web app.
Hyphenate open-source when using the phrase as an adjective (see Merriam-Webster's).
The -n't contractions are fine, but try to avoid using noun-verb contractions, such as ("you're" or "you've"). (See Google's convention).

For more inspiration for the style guide, see the Google's developer documentation style guide or Microsoft's Writing Style Guide.

Configuring Search

The search is powered by Algolia DocSearch, a free service. Thank you, Algolia!

About every 24 hours, Algolia scrapes the website and updates the search index. You do not need to do anything to re-scrape the website and update the search index.

You can modify which content appears in the search index by updating the DocSearch configuration file. The DocSearch configuration file for Standard Notes is available at algolia/docsearch-configs/../standardnotes.json. Try to keep it up to date with algolia/docsearch-configs/../docusaurus-2.json.

Updating KaTeX

The version of KaTeX that we can use depends on the Remark Math that we use. The version of Remark Math that we can use depends on Remark Parse that we use. As of May 7, 2021, Docusaurus does not support the latest version of Remark Parse, so it does not support the latest version of Remark Math and KaTeX. You can follow the developments in Docusaurus #3668 and Docusaurus #4029.

To update KaTeX:

Determine which version of KaTeX you want to use (e.g., v0.12.0).
Create a folder in ./static/katex with the version number as the name of the folder.
Download the zip of the appropriate version from github.com/katex/katex/releases.
Unzip the KaTeX from step 2 and copy the contents into the folder from step 1.
Copy the integrity of the katex.min.css file from the README.md of the unzipped contents from step 3.
Update the href and integrity of the KaTeX stylesheet in docusaurus.config.js.
Check the page for Markdown Math to see if KaTeX is loading properly.

Updating Canonical URLs

You can update the canonical URL of individual docs by importing the CanonicalUrl component defined in ./src/components/CanonicalUrl.js.

Update the relative path as appropriate. To check that the canonical is updated, build the website using yarn build, and test the site using yarn serve.

import CanonicalUrl from '../../src/components/CanonicalUrl';

<CanonicalUrl canonicalUrl="https://standardnotes.org/help/" />;

lyoshenka/docs