standardnotes / docs

[Moved to https://github.com/standardnotes/app/tree/main/packages/docs] Documentation for Standard Notes users and developers | https://docs.standardnotes.com

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.

Directory

This is the structure of the directory:

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
│   └── matomo.js
├── .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, 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  [email protected]:standardnotes/docs.git (fetch)
origin  [email protected]:standardnotes/docs.git (push)

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

git remote set-url origin [email protected]: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.
• 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:

1. Determine which version of KaTeX you want to use (e.g., v0.12.0).
2. Create a folder in ./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.
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.

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.com/help/" />;

docs's Issues

Slack link outdated

The link to the Slack group on the following page is outdated:
https://github.com/standardnotes/docs/blob/main/docs/extensions/publishing.md#questions

Nginx documentation error

On site Securing HTTP traffic of your Sync server https://docs.standardnotes.org/self-hosting/https-support/ the command for testing nginx must be
sudo nginx -t
instead of nginx -t
otherwise nginx will report strange and confusing errors for a correct setup.

Clarify which fields are optional and which fields are not

Hi, I'm trying to implement a standard notes sync server and would like to know which fields are optional and which fields are not. The documentation only said that the api field "must not be null" but there are no such comments for other fields. I doubt that they are all required cause surely a deleted item does not need to have a content field. It would be nice if the documentation could clear things up.

Installing a local extension causes it to get cached, and it can't be changed and re-installed again

I was trying to follow the steps at Local Setup to install a new theme. I ran http-server in a theme extension's directory and installed it with the URL http://localhost:8001/ext.json. This is on Windows. Then I changed some things and uninstalled the extension. When I re-installed the extension, the changes were not reflected in the application. The only way to fix this was to change the extension identifier and port number in the url every time I make a change. It's confusing since otherwise it looks like the install succeeds.

Clarifying the `area` property for components in ext.json

When users set up an extension locally (https://docs.standardnotes.org/extensions/local-setup), there can be some confusion (or just misreading) around what should go under the area property in ext.json. Many just leave the default value, and thus extensions like Folders or Action Bar don't work properly when setup. This occurred to me as well, and I had to do some digging to determine the correct values to use for a given component.

I propose adding a diagram to the aforementioned page under step 4; something like the below would make things crystal clear. Although it would have to be more professional-looking and polished.

In addition, (perhaps) more emphasis should be placed on the url and area properties because those are the important ones that affect the normal function of extensions.

cc @mobitar @TheodoreChu @zsoltszilvai

Sync protocol documentation outdated

I am trying to write my own implementation of Standard Notes sync server (https://github.com/PeterCxy/sfrs), during which I noticed that the documentation on https://docs.standardnotes.org/specification/sync seems to be outdated. Here are several differences I have run into during implementation

1. The /auth and /auth/sign_in interfaces needs to return a user object with uuid and email in addition to the session token
2. The /items/sync interface now uses conflicts instead of unsaved to pass conflicts back to the client

These are the ones I have noticed by far. I think that having the standard documentation up-to-date can facilitate more implementations and also make the protocol itself easier to audit.

In addition, I think that the standard should not force implementations to use standard-compliant JWT, since it contains many pitfalls that makes a truly standard-compliant implementation vulnerable (most real-world implementations should not be actually standard-compliant though). Since I don't think the client should care about what sort of token the server uses, maybe the documentation can just say "the server should return some kind of session token that can be used to identify the user and the session".

How to get a dock icon for your theme

This should be added to the documentation:

In order to get SN to display a dock icon for your theme (a circle in the lower right corner of the app that allows you to quickly toggle themes), add the following payload into the your ext.json file:

"dock_icon": {
   "type": "circle",
   "background_color": "#086DD6",
   "foreground_color": "#ffffff",
   "border_color": "#086DD6"
}