Add documentation style guide and tool configs

.gitattributes

@@ -5,7 +5,7 @@
 # linguist-generated causes generated files to not be expanded during code review.
 
 /database/mock/*.go linguist-generated=true
-/docs/docs/cli/*.md linguist-generated=true
+/docs/docs/ref/cli/*.md linguist-generated=true
 /docs/docs/ref/schema.md linguist-generated=true
 /docs/docs/ref/proto.md linguist-generated=true
 /pkg/api/openapi/** linguist-generated=true

.github/dependabot.yml

@@ -29,6 +29,9 @@ updates:
       docusaurus:
         patterns:
           - "*docusaurus*"
+      eslint:
+        patterns:
+          - "*eslint*"
     ignore:
       # facebook/docusaurus#4029 suggests MDX v2 will only be in the v3 release.
       # facebook/docusaurus#9053 has some more details on the migration.

docs/.markdownlint-cli2.jsonc

@@ -0,0 +1,11 @@
+{
+  "gitignore": true,
+  "globs": ["**/*.md"],
+  "ignores": [
+    "node_modules/",
+    ".docusaurus",
+    "build/",
+    "docs/ref/cli/",
+    "docs/ref/proto.md",
+  ],
+}

docs/.markdownlint.json

@@ -0,0 +1,37 @@
+{
+  "code-block-style": {
+    "style": "fenced"
+  },
+  "code-fence-style": {
+    "style": "backtick"
+  },
+  "emphasis-style": {
+    "style": "underscore"
+  },
+  "heading-style": {
+    "style": "atx"
+  },
+  "hr-style": {
+    "style": "---"
+  },
+  "line-length": {
+    "code_blocks": false,
+    "line_length": 80,
+    "tables": false
+  },
+  "no-bare-urls": false,
+  "no-duplicate-heading": false,
+  "proper-names": {
+    "code_blocks": false,
+    "names": ["GitHub", "GitLab", "Bitbucket"]
+  },
+  "strong-style": {
+    "style": "asterisk"
+  },
+  "table-pipe-style": {
+    "style": "leading_and_trailing"
+  },
+  "ul-style": {
+    "style": "dash"
+  }
+}

docs/.prettierignore

@@ -0,0 +1,7 @@
+node_modules/
+.docusaurus/
+build/
+
+# Auto-generated files
+docs/ref/cli/*.md
+docs/ref/proto.md

docs/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "jsxSingleQuote": true,
+  "printWidth": 80,
+  "proseWrap": "always",
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "useTabs": false
+}

docs/README.md

@@ -1,25 +1,66 @@
-# Docs for Minder
+# Minder documentation
+
+This directory contains the user documentation for Minder, hosted at
+<https://mindersec.github.io>.
+
+The docs are built with [Docusaurus](<[https://](https://docusaurus.io/)>), an
+open source static website generator optimized for documentation use cases.
+
+## Contributing to docs
+
+We welcome community contributions to the Minder documentation - if you find
+something missing, wrong, or unclear, please let us know via an issue or open a
+PR!
+
+Please review the [style guide](./STYLE-GUIDE.md) for help with voice, tone, and
+formatting.
 
 ## Building the docs locally
 
-Start from the top level directory of the repository.
+Start from the top level directory of the `minder` repository and generate the
+CLI docs:
 
-Generate the CLI docs
-```
+```bash
 make cli-docs
 ```
 
-Build the docs
-```
-cd docs
-```
+Run a preview server:
 
+```bash
+npm run start
 ```
+
+Your browser should automatically open to <http://localhost:3000>
+
+Build the docs:
+
+```bash
+cd docs
 npm run build
 ```
 
 Serve the docs
-```
+
+```bash
 npm run serve -- --port 3001
 ```
+
 Visit http://localhost:3001/ to view the docs.
+
+## Formatting
+
+Before you submit a PR, please check for formatting and linting issues:
+
+```bash
+npm run prettier
+npm run markdownlint
+npm run eslint
+```
+
+To automatically fix issues:
+
+```bash
+npm run prettier:fix
+npm run markdownlint:fix
+npm run eslint:fix
+```