# Standard Notes Documentation
## Introduction
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. You can read the about the full features of Docusaurus on the official [Docusaurus documentation](https://docsaurus.io).
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](./.github/workflows/deploy.yml). The URL for the website is located at [static/CNAME](static/CNAME).
### Directory
This is the structure of the directory:
```sh
docs
├── docs
│ ├── account
│ ├── extended
│ ├── extensions
│ ├── listed
│ ├── privacy
│ ├── self-hosting
│ ├── specification
│ ├── troubleshooting
│ ├── usage
│ ├── contribute.md
│ ├── template.md
│ └── welcome.md
├── src
│ ├── components
│ │ └── CanonicalUrl.js
│ ├── css
│ │ └── custom.scss
│ └── pages
│ ├── archive
│ ├── docs
│ ├── listed
│ ├── self-hosting
│ ├── standard-file
│ └── styles.module.css
├── static
│ ├── img
│ ├── katex
│ ├── .nojekyll
│ ├── CNAME
├── .gitignore
├── .prettierrc
├── docusaurus.config.js
├── LICENSE
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
```
### Files
- `.gitignore` - This specifies which files Git should ignore when committing and pushing to remote repositories.
- `.prettierrc` - This specifies the rules for [Prettier](https://prettier.io/docs/en/configuration.html), 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](https://docusaurus.io/docs/configuration) and full documentation for the API is [here](https://docusaurus.io/docs/docusaurus.config.js).
- `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](https://docusaurus.io/docs/sidebar).
- `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](https://docusaurus.io/docs/docs-introduction) 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](https://docusaurus.io/docs/styling-layout/).
The `.js` files in `src/pages` are [Docusaurus pages](https://docusaurus.io/docs/creating-pages) that serve as redirects. You can also set up redirects using the [plugin-client-redirects](https://docusaurus.io/docs/api/plugins/@docusaurus/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](https://docusaurus.io/docs/cli).
### Prerequisites
To get started with developing this website, you need to install the following technologies on your device
- [Node.js](https://nodejs.org/en/download/) version >= 12.13.0 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed
- [Yarn](https://yarnpkg.com/en/) 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](https://code.visualstudio.com/) - A text editor to edit the source files of your editor
- [Git](https://git-scm.com/downloads) - A tool for managing different versions of the website
### Installation
```console
yarn install
```
This command reads the dependencies from the `package.json` file, updates the dependencies of those dependencies in
### Start
```console
yarn start
```
This command starts a local development server at port `3002`, opens up a browser window, and loads [localhost:3002](localhost:3002). Most changes are reflected live without having to restart the server. To close this, press Ctrl/Cmd+C.
### Build
```console
yarn build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
### Serve
```console
yarn serve
```
Serve your built website locally through port `3000`. Open [localhost:3000](localhost:3000) to test the production build of your website before committing it to Git.
### Deployment
```console
GIT_USER= 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](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-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:
```console
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:
```console
git remote set-url origin git@github.com:standardnotes/docs.git
```
## Creating a new documentation file
1. 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`).
2. Copy the contents of `docs/template` into your new documentation file. The template contains standard keywords and a link to the standard meta image.
3. In VSCode, you can easily change `Template` to be desired word or phrase by right-clicking the word `Template` then clicking "Change all occurrences".
4. Finish writing the new documentation.
5. Add the `id` to `sidebars.js`.
6. 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](https://app.standardnotes.com).
- Hyphenate `open-source` when using the phrase as an adjective (see [Merriam-Webster's](https://www.merriam-webster.com/dictionary/open-source)).
- 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](https://developers.google.com/style/contractions)).
For more inspiration for the style guide, see the [Google's developer documentation style guide](https://developers.google.com/style) or [Microsoft's Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
## Configuring Search
The search is powered by [Algolia DocSearch](https://docsearch.algolia.com/), 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](https://github.com/algolia/docsearch-configs/blob/master/configs/standardnotes.json). Try to keep it up to date with [algolia/docsearch-configs/../docusaurus-2.json](https://github.com/algolia/docsearch-configs/blob/master/configs/docusaurus-2.json).
## Updating KaTeX
The version of KaTeX that we can use depends on the [Remark Math](https://github.com/remarkjs/remark-math) that we use. The version of Remark Math that we can use depends on [Remark Parse](https://github.com/remarkjs/remark/releases) 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](https://github.com/facebook/docusaurus/issues/3668) and [Docusaurus #4029](https://github.com/facebook/docusaurus/issues/4029).
To update KaTeX:
1. Determine which version of KaTeX you want to use (e.g., `v0.12.0`).
2. Create a folder in [./static/katex](./static/katex) with the version number as the name of the folder.
3. Download the zip of the appropriate version from [github.com/katex/katex/releases](https://github.com/KaTeX/KaTeX/releases).
4. Unzip the KaTeX from step 2 and copy the contents into the folder from step 1.
5. Copy the `integrity` of the `katex.min.css` file from the `README.md` of the unzipped contents from step 3.
6. Update the `href` and `integrity` of the KaTeX stylesheet in `docusaurus.config.js`.
7. 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](./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`.
```jsx
import CanonicalUrl from '../../src/components/CanonicalUrl';
;
```