feat: configuration files md

docs/advanced/configuration-files/docusaurus-config.mdx

@@ -2,3 +2,11 @@
 title: docusaurus.config.js
 sidebar_position: 3
 ---
+
+The `docusaurus.config.js` is highly customizable and it would be too difficult to list all of its features and functions exhaustively here.
+
+The config which comes with this repo has some comments embedded to help direct what a setting is for.
+
+It is also very helpful to look at how Docusaurus themselves set up their own [website](https://docusaurus.io) which uses their own docs. You can see their set up [**here**](https://github.com/facebook/docusaurus/blob/main/website/docusaurus.config.js).
+
+You can also find a [**full reference**](https://docusaurus.io/docs/api/docusaurus-config) to the configuration file.

docs/advanced/configuration-files/package.mdx

@@ -1,4 +1,88 @@
 ---
 title: package.json
-sidebar_position: 2
+sidebar_position: 1
 ---
+
+It should not be necessary to change the `package.json` very often.
+
+This page will describe what each dependency is and why it is included.
+
+## Docusaurus core dependencies
+
+The following are **core** Docusaurus dependencies and they should _not_ be removed.
+
+- `@docusaurus/core`
+- `@docusaurus/preset-classic`
+- `prism-react-renderer`
+- `@mdx-js/react`
+- `clsx`
+- `react`
+- `react-dom`
+- `typescript`
+
+:::tip
+
+For [extra safety](https://stackoverflow.com/a/22345808), you may also choose to use `~` on the versions instead of `^` if you prefer.
+
+:::
+
+## Docusaurus plugins and extra dependencies
+
+- [`docusaurus-plugin-openapi-docs`](https://github.com/cloud-annotations/docusaurus-openapi)
+- [`docusaurus-theme-openapi-docs`](https://github.com/cloud-annotations/docusaurus-openapi)
+- [`redocusaurus`](https://github.com/rohit-gohri/redocusaurus)
+- [`remark-docusaurus-tabs`](https://github.com/mccleanp/remark-docusaurus-tabs)
+
+## Dev dependencies
+
+### Docusaurus
+
+- `@docusaurus/module-type-aliases`
+- `@tsconfig/docusaurus`
+
+### `commitlint`
+
+- `@commitlint/cli`
+- `@commitlint/config-conventional`
+
+### `semantic-release`
+
+- `semantic-release`
+- `@semantic-release/changelog`
+- `@semantic-release/commit-analyzer`
+- `@semantic-release/git`
+- `@semantic-release/github`
+- `@semantic-release/npm`
+- `@semantic-release/release-notes-generator`
+
+### `cspell`
+
+- `cspell`
+
+### `eslint`
+
+- `@typescript-eslint/eslint-plugin`
+- `@typescript-eslint/parser`
+- `eslint`
+- `eslint-config-airbnb-typescript`
+- `eslint-config-prettier`
+- `eslint-import-resolver-typescript`
+- `eslint-plugin-import`
+- `eslint-plugin-jsx-a11y`
+- `eslint-plugin-prettier`
+- `eslint-plugin-react`
+- `eslint-plugin-react-hooks`
+
+### `stylelint`
+
+- `stylelint`
+- `stylelint-config-prettier`
+- `stylelint-config-standard`
+
+### Miscellaneous
+
+- `cz-conventional-changelog`
+- `husky`
+- `lint-staged`
+- `prettier`
+- `tsc-files`

docs/advanced/configuration-files/sidebars.mdx

@@ -1,6 +1,6 @@
 ---
 title: sidebars.js
-sidebar_position: 4
+sidebar_position: 2
 ---
 
 By default, the sidebars are defined in `sidebars.js` in the root folder of this repo.
@@ -23,3 +23,69 @@ const config = {
   ],
 };
 ```
+
+Under the key `config > themeConfig > navbar > items > sidebarId`, you can specify the key ID that is defined in the `sidebars` variable in `sidebars.js`. As an example, this can be used if you want a different sidebar for a subset of docs.
+
+:::note
+
+Be aware that if you take the shortcut of using the type `autogenerated` and `dirname`, Docusaurus will recursively take all Markdown files in that folder and make it available on the sidebar.
+
+The only way to prevent this is to explicitly define every page and category that you want in your sidebar. See [example](https://github.com/facebook/docusaurus/blob/main/website/sidebars.js) from Docusaurus' website.
+
+:::
+
+## Using `_category_.json` with autogenerated
+
+:::tip
+
+It is worth checking out the official docs regarding the [sidebar](https://docusaurus.io/docs/sidebar/items) and [autogenerated](https://docusaurus.io/docs/sidebar/autogenerated).
+
+:::
+
+The `_category_.json` file is usually used in sub-folders where the autogenerate functionality is used. It allows you to tell the `autogenerate` feature to respect ordering and customize the category label for the folder that it appears as in the sidebar.
+
+```json title="docs/advanced/configuration-files/_category_.json"
+{
+  "label": "Configuration Files",
+  "position": 6, // position under in the sidebar under the advanced
+  "link": {
+    "type": "generated-index", // by specifying this, clicking on "Configuration Files" in the sidebar will create a generated page with a list of sub-pages that it contains
+    "description": "Advanced customization of configuration files." // this will appear in the description under the title for the generated page
+  }
+}
+```
+
+If you _don't_ want to generate for when you click on the folder, you can delete the `link` key completely.
+
+Or if you want it to point to a custom page instead of an autogenerated one:
+
+```json
+{
+  "label": "Configuration Files",
+  "position": 6, // position under in the sidebar under the advanced
+  "link": {
+    "type": "doc", // type must be doc
+    "id": "deploy/install-index" //
+  }
+}
+```
+
+## Custom slugs
+
+Under the `link` key, you can also specify the `slug`.
+
+By default autogenerated pages have the URL as `{baseURL}/category/yourDirName`.
+
+```json
+{
+  "label": "Configuration Files",
+  "position": 6, // position under in the sidebar under the advanced
+  "link": {
+    "type": "generated-index", // by specifying this, clicking on "Configuration Files" in the sidebar will create a generated page with a list of sub-pages that it contains
+    "description": "Advanced customization of configuration files.", // this will appear in the description under the title for the generated page
+    "slug": "configuration-files" // specify your slug
+  }
+}
+```
+
+You can set the slug to something else if you want to omit the `category` subDir.