---
title: Help
description: Because sometimes I forget to how to use the software
toc_min_heading_level: 2
toc_max_heading_level: 5
---
# Help
Because sometimes I forget how to drive the software I'm running.
---
### Todo
- Make all links absolute. ( e.g. /docs/sass/ai ) While training the documents with OpenAI, I noticed that some of the link references were not absolute.
- Create Github Actions to rebuild a Supabase index of the documents on every commit for the AI Assistant to use.
---
### Log
```mermaid
gitGraph
commit id: ".md files" tag: "v0.0.1"
commit
branch gitbook
commit id: "mv to gitbook" tag: "v0.0.2"
commit
branch docusaurus
checkout docusaurus
commit id: "docusaurus" tag: "v0.0.3"
commit
checkout main
merge docusaurus
```
#### Repos
- https://code.davidawindham.com/david/til
- https://github.com/windhamdavid/til
### Docusaurus
[https://docusaurus.io/docs](https://docusaurus.io/docs)
```bash
npm install
npm run start
npm run build
npm run serve
```
**23/11/12** - Docusaurus updated 2.4.3 ππΌ 3.0.0 and React 17.0.2 ππΌ 18.2.0
:::danger
This introduced a bunch of breaking errors in the markdown formatting via the MDX formatting that are documented at:
- [https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3](https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3)
- [https://github.com/facebook/docusaurus/discussions/9312](https://github.com/facebook/docusaurus/discussions/9312).
Went in and cleaned up the markdown formatting - mostly the tags on links and indented code highlighting formatting.
:::
```bash
david@ovidπ :~/sites/daw_til(mainβ) Β» npm outdated
Package Current Wanted Latest Location Depended by
@docusaurus/core 2.4.3 3.0.0 3.0.0 node_modules/@docusaurus/core daw_til
@docusaurus/plugin-content-blog 2.4.3 3.0.0 3.0.0 node_modules/@docusaurus/plugin-content-blog daw_til
@docusaurus/preset-classic 2.4.3 3.0.0 3.0.0 node_modules/@docusaurus/preset-classic daw_til
@docusaurus/theme-mermaid 2.4.3 3.0.0 3.0.0 node_modules/@docusaurus/theme-mermaid daw_til
@mdx-js/react 1.6.22 1.6.22 3.0.0 node_modules/@mdx-js/react daw_til
clsx 1.2.1 1.2.1 2.0.0 node_modules/clsx daw_til
docusaurus-lunr-search 3.0.0 3.3.0 3.3.0 node_modules/docusaurus-lunr-search daw_til
react 17.0.2 17.0.2 18.2.0 node_modules/react daw_til
react-dom 17.0.2 17.0.2 18.2.0 node_modules/react-dom daw_til
david@ovidπ :~/sites/daw_til(mainβ‘) Β» npm list
daw-til-2@0.0.1 /Users/david/Sites/daw_til
βββ @docusaurus/core@3.0.0
βββ @docusaurus/plugin-content-blog@3.0.0
βββ @docusaurus/preset-classic@3.0.0
βββ @docusaurus/theme-mermaid@3.0.0
βββ @mdx-js/mdx@3.0.0
βββ @mdx-js/react@3.0.0
βββ clsx@2.0.0
βββ docusaurus-lunr-search@3.3.0
βββ docusaurus-plugin-matomo@0.0.6
βββ markprompt@0.1.7
βββ plugin-image-zoom@1.1.0 (git+ssh://git@github.com/flexanalytics/plugin-image-zoom.git#8e1b866c79ed6d42cefc4c52f851f1dfd1d0c7de)
βββ react-dom@18.2.0
βββ react-player@2.13.0
βββ react@18.2.0
```
**23/09/23** - docusaurus updated - 2.4.1 ππΌ 2.4.3 -> left react at 17 for now, but updated the react player to 2.13.
```bash
david@ovidπ :~/sites/daw_til(mainβ‘) Β» npm list
daw-til-2@0.0.1 /Users/david/Sites/daw_til
βββ @docusaurus/core@2.4.3
βββ @docusaurus/plugin-content-blog@2.4.3
βββ @docusaurus/preset-classic@2.4.3
βββ @docusaurus/theme-mermaid@2.4.3
βββ @mdx-js/react@1.6.22
βββ clsx@1.2.1
βββ docusaurus-lunr-search@3.0.0
βββ docusaurus-plugin-matomo@0.0.6
βββ markprompt@0.1.7
βββ plugin-image-zoom@1.1.0
βββ react-dom@17.0.2
βββ react-player@2.13.0
βββ react@17.0.2
david@ovidπ :~/sites/daw_til(mainβ‘) Β» npm outdated
Package Current Wanted Latest Location Depended by
@mdx-js/react 1.6.22 1.6.22 2.3.0 node_modules/@mdx-js/react daw_til
clsx 1.2.1 1.2.1 2.0.0 node_modules/clsx daw_til
react 17.0.2 17.0.2 18.2.0 node_modules/react daw_til
react-dom 17.0.2 17.0.2 18.2.0 node_modules/react-dom daw_til
```
**23/08/20** - added an image zoom plugin from [https://github.com/flexanalytics/plugin-image-zoom](https://github.com/flexanalytics/plugin-image-zoom) because I didn't like linking to the images or having them constrained between the sidebars.
**23/08/18** - updated notes structure to include some personal documents like /documents/family/mom/mom.md which is actually a directory outside of the site build on my computer. I ignore them in the builds and repos. The reason for this is that the more I use machine learning against my own documents, the more the information becomes valuable in vector searches. Because of that, I'm rethinking the way I even organize documents on my computer. For instance this doc when I'm talking to my mom on the phone about whatever, I can reference references I've previously made.
**23/05/24** - docusaurus updated - 2.4.0 ππΌ 2.4.1
```bash
david@ovidπ :~/sites/daw_til(mainβ‘) Β» npm list
daw-til-2@0.0.1 /Users/david/Sites/daw_til
βββ @docusaurus/core@2.4.1
βββ @docusaurus/plugin-content-blog@2.4.1
βββ @docusaurus/preset-classic@2.4.1
βββ @docusaurus/theme-mermaid@2.4.1
βββ @mdx-js/react@1.6.22
βββ clsx@1.2.1
βββ docusaurus-lunr-search@2.3.2
βββ docusaurus-plugin-matomo@0.0.6
βββ markprompt@0.1.7
βββ react-dom@17.0.2
βββ react-player@2.12.0
βββ react@17.0.2
```
**23/05/09**
- added react-player
- added markprompt
```bash
david@ovidπ :~/sites/daw_til(mainβ‘) Β» npm list
daw-til-2@0.0.1 /Users/david/Sites/daw_til
βββ @docusaurus/core@2.4.0
βββ @docusaurus/plugin-content-blog@2.4.0
βββ @docusaurus/preset-classic@2.4.0
βββ @docusaurus/theme-mermaid@2.4.0
βββ @mdx-js/react@1.6.22
βββ clsx@1.2.1
βββ docusaurus-lunr-search@2.3.2
βββ docusaurus-plugin-matomo@0.0.6
βββ markprompt@0.1.7
βββ react-dom@17.0.2
βββ react-player@2.12.0
βββ react@17.0.2
```
**23/03/24**
- npm up doc/core 2.3.1 -> 2.4.0
```bash
# still have issues with mdx-js/react@latest - holding it in place
david@ovidπ :~/sites/daw_til(mainβ‘) Β» npm list
daw-til-2@0.0.1 /Users/david/Sites/daw_til
βββ @docusaurus/core@2.4.0
βββ @docusaurus/plugin-content-blog@2.4.0
βββ @docusaurus/preset-classic@2.4.0
βββ @docusaurus/theme-mermaid@2.4.0
βββ @mdx-js/react@1.6.22
βββ clsx@1.2.1
βββ docusaurus-lunr-search@2.3.2
βββ docusaurus-plugin-matomo@0.0.6
βββ react-dom@17.0.2
βββ react@17.0.2
```
**22/01/31**
- upgraded to docusaurus v2.3.0
```shell
david@ovidπ :~/sites/daw_til(masterβ‘) Β» npm list
daw-til-2@0.0.1 /Users/david/Sites/daw_til
βββ @docusaurus/core@2.3.0
βββ @docusaurus/plugin-content-blog@2.3.0
βββ @docusaurus/preset-classic@2.3.0
βββ @docusaurus/theme-mermaid@2.3.0
βββ @mdx-js/react@1.6.22
βββ clsx@1.2.1
βββ docusaurus-lunr-search@2.3.2
βββ docusaurus-plugin-matomo@0.0.6
βββ react-dom@17.0.2
βββ react@17.0.2
```
**22/11/13**
- added a Reader page
- move branch master -> main for Git
- addped mermaid and created overview graph
- upgraded to v.2.2.0
```shell
david@ovidπ :~/sites/daw_til(masterβ‘) Β» npm outdated 127 β΅
Package Current Wanted Latest Location Depended by
@docusaurus/core 2.0.0-beta.15 2.2.0 2.2.0 node_modules/@docusaurus/core daw_til
@docusaurus/preset-classic 2.0.0-beta.15 2.2.0 2.2.0 node_modules/@docusaurus/preset-classic daw_til
@mdx-js/react 1.6.22 1.6.22 2.1.5 node_modules/@mdx-js/react daw_til
clsx 1.1.1 1.2.1 1.2.1 node_modules/clsx daw_til
docusaurus-lunr-search 2.1.15 2.3.1 2.3.1 node_modules/docusaurus-lunr-search daw_til
react 17.0.2 17.0.2 18.2.0 node_modules/react daw_til
react-dom 17.0.2 17.0.2 18.2.0 node_modules/react-dom daw_til
```
- colorMode.switchConfig is deprecated #[6771](https://github.com/facebook/docusaurus/pull/6771) rm'd -
```js
switchConfig: {
darkIcon: '\u2800',
darkIconStyle: {
marginLeft: '1px',
},
lightIcon: '\u2800',
lightIconStyle: {
marginLeft: '1px',
},
},
```
- lunr-search broken ( see: https://github.com/praveenn77/docusaurus-lunr-search/pull/91 ) made the following change in the plugin to fix
```diff
src/theme/SearchBar/lunar-search.js
29 - url: this.baseUrl !== '/' || doc.url.charAt(0) !== '/' ? this.baseUrl + doc.url : doc.url,
+ url: doc.url,
```
**12/04/2021**
- added in [Notes](/notes) for non-technical docs
- upgraded to v.2.0.0-beta.13
**11/10/2021**
- Updated the Docusaurus & NPM packages.
- Combined my old [awesome-david](/lists) repo into it for simplicity and rebuilt.
**03/18/2021**
Migrated this version from Gitbook because it wasn't playing nicely with Node.js v14 and it had a couple security vulnerabilities in the packages. Gitbook stop supporting the open source version likely for business reasons, so I migrated it all to ~~[https://docsify.js.org/](https://docsify.js.org/)~~... didn't do docsify because I can't generate static HTML which is what my DOM parser depends on to pull content elsewhere. Decided on using [https://docusaurus.io/](https://docusaurus.io/) instead. It required a bit of cleanup in the Markdown to do so. See: [https://davidawindham.com/til/help](/help)
**05/02/2017**
While working on another project yesterday afternoon, I ran into set of documentation ([https://docs.feathersjs.com/](https://docs.feathersjs.com/)) that I spent a lot of time reading and will likely forget about sometime soon after I abandon using the library in other projects. Of course I stuffed a bookmark of the documentation into my quasi organized set of chrome bookmarks based on each project, but the fact that the documentation was hosted using [Gitbook](https://github.com/GitbookIO/gitbook), reminded me of a practice I've seen others do.
**03/18/21** - **Gotta Migrate** my TIL. Just noticed that gitbook doesn't play nicely with Node.js v14.
```bash
david@macsπΆ:~/sites/daw_til(masterβ‘) Β» gitbook serve --no-live
/Users/david/.nvm/versions/node/v14.15.4/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
if (cb) cb.apply(this, arguments)
TypeError: cb.apply is not a function
at /Users/david/.nvm/versions/node/v14.15.4/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
at FSReqCallback.oncomplete (fs.js:184:5)
david@macsπΆ:~/sites/daw_til(masterβ‘) Β» node -v
v14.15.4
david@macsπΆ:~/sites/daw_til(masterβ‘) Β» nvm ls
v6.10.3
v6.11.2
v7.6.0
v8.4.0
v8.11.4
v8.12.0
v10.16.3
-> v14.15.4
system
default -> 14 (-> v14.15.4)
unstable -> N/A (default)
node -> stable (-> v14.15.4) (default)
stable -> 14.15 (-> v14.15.4) (default)
iojs -> iojs- (-> system) (default)
lts/* -> lts/fermium (-> v14.15.4)
lts/argon -> v4.9.1 (-> N/A)
lts/boron -> v6.17.1 (-> N/A)
lts/carbon -> v8.17.0 (-> N/A)
lts/dubnium -> v10.23.2 (-> N/A)
lts/erbium -> v12.20.1 (-> N/A)
lts/fermium -> v14.15.4
david@macsπΆ:~/sites/daw_til(masterβ‘) Β» nvm use 10.16.3
Now using node v10.16.3 (npm v7.5.4)
david@macsπΆ:~/sites/daw_til(masterβ‘) Β» gitbook serve --no-live
info: 18 plugins are installed...
```
**3/14/20** Ran into a couple errors with Gitbook and noticed that they are deprecating the open source version. Will need to migrate Gitbook to Docsify:
* [https://github.com/GitbookIO/gitbook](https://github.com/GitbookIO/gitbook)
* [https://github.com/docsifyjs/docsify/](https://github.com/docsifyjs/docsify/)
* the current [Gitbook Search Plugin](https://github.com/lwdgit/gitbook-plugin-search-plus) key to the current setup and the docsify search is good.
* ran package upgrades before migration.
* docsify doesn't support all prism languages - [https://docsify.js.org/#/language-highlight?id=language-highlight](https://docsify.js.org/#/language-highlight?id=language-highlight)
* [gitbook-prism-plugin](https://github.com/gaearon/gitbook-plugin-prism) has an outdated version of [prism](https://www.npmjs.com/package/prismjs).
* forked pkg to [https://www.npmjs.com/package/gitbook-plugin-prism-dw](https://www.npmjs.com/package/gitbook-plugin-prism-dw)
* add "gitbook-plugin-prism-dw": "^2.4.1" to pkg.json
#### migrate
```bash
# install docsify globally
npm i docsify-cli -g
# copy existing repo
mv til/ til_old
cp /til_old /til
docsify init til/
# Rename summary.md to _sidebar.md
mv summary.md _sidebar.md
#add loadSidebar: true to window.$docsify in index.html
docsify serve
```
#### migrate notes:
```js
{
"name": "windhamdavid_til",
"version": "1.0.0",
"description": "my til gitbook",
"dependencies": {
"gitbook": "^3.2.3",
"gitbook-plugin-ace": "^0.3.2",
"gitbook-plugin-advanced-emoji": "^0.2.2",
"gitbook-plugin-anchors": "^0.7.1",
"gitbook-plugin-github-embed": "^1.3.1",
"gitbook-plugin-piwik": "^0.2.1",
"gitbook-plugin-search-plus": "^1.0.4-alpha-3",
"gitbook-plugin-toggle-chapters": "0.0.3",
"gitbook-plugin-toggle-headers": "^0.1.0",
"gitbook-plugin-video": "0.0.3"
},
"devDependencies": {},
"repository": {
"type": "git",
"url": "https://github.com/windhamdavid/til.git"
},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "David A. Windham",
"private": true,
"license": "UNLICENSED",
"homepage": "https://davidawindham.com"
}
```
```sh
david@macs:~/sites/til(masterβ‘) Β» npm outdated 130 β΅
Package Current Wanted Latest Location
gitbook-plugin-search-plus 1.0.3 1.0.4-alpha-3 1.0.4-alpha-3 windhamdavid_til
gitbook 3.2.2 3.2.3 2.6.9 windhamdavid_til
gitbook-plugin-github-embed 1.1.2 1.3.1 1.3.1 windhamdavid_til
```
---
### Admonitions
:::note
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
### Mermaid
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
```mermaid
graph TD
A(Does your flowchart have arrows?) --> B[No]
A --> C[yes]
B --> D(Add them already)
C --> E(Yay, what a great flowchart!)
D -.->|you can even add text to them| A
```
---
### Creating Docs
Create a Markdown file in /docs/doc.md
Add to sidebars.js
### Meta Data using Front Matter
```bash
---
id: my-doc
title: My document title
description: My document description
sidebar_label: My doc
---
Markdown content
```
### Markdown links
url paths or relative file paths
```bash
[Create a page](/create-a-page)
[Create a page](./create-a-page.md)
```
---
### Gitbook:
[https://github.com/GitbookIO/gitbook](https://github.com/GitbookIO/gitbook)
[https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md](https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md)
[https://toolchain.gitbook.com/](https://toolchain.gitbook.com/)
```
npm install -g gitbook-cli
cd sites/til
gitbook help
gitbook build .
gitbook serve .
http://localhost:4000/
```
run for production without livereload.js
```
gitbook serve --no-live
```
### Markdown:
[Markdown Cheatsheet from Github](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
[Markdown Cheatsheet](https://gist.github.com/jonschlinkert/5854601)
#### Headers
```markdown
# h1
## h2
### h3
#### h4
##### h5
###### h6
```
```markdown
Header 1
========
```
```markdown
Header 2
--------
```
#### Emphasis
```markdown
*italic*
_italic_
```
```markdown
**bold**
__bold__
```
```markdown
***bold italic***
___bold italic___
```
```markdown
~~strikethrough~~
```
```markdown
`code`
```
#### Lists
```markdown
* Item 1
* Item 2
```
```markdown
- Item 1
- Item 2
```
```markdown
- [ ] Checkbox off
- [x] Checkbox on
```
```markdown
1. Item 1
2. Item 2
```
#### Links
```markdown
[link](http://google.com)
```
```markdown
[link][google]
[google]: http://google.com
```
```markdown
```
#### Images
```markdown


![Image alt text][img]
```
```markdown
[img]: http://foo.com/img.jpg
```
#### Code
```
4 space indent
makes a code block
```
~~~markdown
```
code fences
```
~~~
~~~markdown
```js
codeFences.withLanguage()
```
~~~
#### Blockquotes
```markdown
> This is
> a blockquote
>
> > Nested
> > Blockquote
```
#### Horizontal line
```markdown
----
```
```markdown
****
```
#### Tables
```markdown
| Column 1 Heading | Column 2 Heading |
| ---------------- | ---------------- |
| Some content | Other content |
```
```markdown
Column 1 Heading | Column 2 Heading
--- | ---
Some content | Other content
```
### Code:
#### Piwik Plugin
[https://github.com/emmanuel-keller/gitbook-plugin-piwik](https://github.com/emmanuel-keller/gitbook-plugin-piwik)
use the language identifier after the back ticks for the code block in markdown
```html