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โ
Reposโ
Docusaurusโ
npm install
npm run start
npm run build
npm run serve
- 24/24/02 - 3.6.1 -> 3.6.3
- 24/11/17 - upgrades ( 3.5.2 ๐๐ผ 3.6.1 ) all good ๐๐ผ
- 3.6 switched to Rust ๐ฆ rspack, SWC, Lightning CSS for faster builds
- 24/09/02 - upgrades ( 3.4.0 ๐๐ผ 3.5.2 ) all good ๐๐ผ
- 24/07/11 - upgrades ( 3.3.2 ๐๐ผ 3.4.0 ) all good ๐๐ผ
- 24/05/15 - upgrades ( 3.1.1 ๐๐ผ 3.3.2 ) all good ๐๐ผ
npm install @docusaurus/core@latest @docusaurus/plugin-content-blog@latest @docusaurus/preset-classic@latest @docusaurus/theme-mermaid@latest --save
24/01/28 - upgrades ( 3.0.1 ๐๐ผ 3.1.1 ) no overides. didn't have to reswizzle. Watch the letter casing, anchors, and relative URLs because the broken link checker has gotten more strict.
Watch the letter casing, anchors, and relative URLs because the broken link checker has gotten more strict.
david@ovid๐ :~/sites/daw_til(mainโก) ยป npm outdated
david@ovid๐ :~/sites/daw_til(mainโก) ยป npm list
daw-til-2@0.0.3 /Users/david/Sites/daw_til
โโโ @docusaurus/core@3.1.1
โโโ @docusaurus/plugin-content-blog@3.1.1
โโโ @docusaurus/preset-classic@3.1.1
โโโ @docusaurus/theme-mermaid@3.1.1
โโโ @mdx-js/mdx@3.0.0
โโโ @mdx-js/react@3.0.0
โโโ clsx@2.1.0
โโโ docusaurus-lunr-search@3.3.2
โโโ docusaurus-plugin-matomo@0.0.8
โโโ 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.14.1
โโโ react@18.2.0
23/12/12 - ๐ฅneeded a way to preface my posts
and wanted to change the default width so I swizzle
'd the BlogListPage
and BlogLayout
to widen it with col--9
.
npm run swizzle @docusaurus/theme-classic BlogLayout -- --eject
npm run swizzle @docusaurus/theme-classic BlogListPage -- --eject
line 15 of BlogLayout/index.js
<main
className={clsx('col', {
//'col--7': hasSidebar,
'col--9': hasSidebar,
'col--9 col--offset-1': !hasSidebar,
})}
...
</main>
line 33 of BlogListPage/index.js
<BlogLayout sidebar={sidebar}>
<h1>Posts</h1>
<p>...</p>
<hr/>
<br/>
<BlogPostItems items={items} />
<BlogListPaginator metadata={metadata} />
</BlogLayout>
23/11/27 - noticed my Lunr search was kicking JavaScript errors because I had swizzle
'd it in a previous version and needed to eject
it before the build. ( see github repo comment )
david@ovid๐ :~/sites/daw_til(mainโ) ยป npm run swizzle docusaurus-lunr-search SearchBar -- --eject
> daw-til-2@0.0.3 swizzle
> docusaurus swizzle docusaurus-lunr-search SearchBar --eject
[WARNING]
Swizzle action eject is unsafe to perform on SearchBar.
It is more likely to be affected by breaking changes in the future
If you want to swizzle it, use the `--danger` flag, or confirm that you understand the risks.
โ Do you really want to swizzle this unsafe internal component? โบ YES: I know what I am doing!
[SUCCESS]
Ejected SearchBar from docusaurus-lunr-search to
- "daw_til/src/theme/SearchBar/DocSearch.js"
- "daw_til/src/theme/SearchBar/HighlightSearchResults.jsx"
- "daw_til/src/theme/SearchBar/algolia.css"
- "daw_til/src/theme/SearchBar/index.jsx"
- "daw_til/src/theme/SearchBar/lunar-search.js"
- "daw_til/src/theme/SearchBar/styles.css"
- "daw_til/src/theme/SearchBar/templates.js"
- "daw_til/src/theme/SearchBar/utils.js"
Also noticed that since it now uses the default Algolia search elements which includes dark mode, I had to change the styling on it in /src/css/custom.css
.
[data-theme='dark'] .ds-dropdown-menu {
--ifm-background-color: #383a42;
border-color: #535763;
}
v3.0.0โ
23/11/12 - Docusaurus updated 2.4.3 ๐๐ผ 3.0.0 and React 17.0.2 ๐๐ผ 18.2.0
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
Docusaurus v3 now requires React 18 and Typescript 5
This introduced a bunch of breaking errors in the markdown formatting via the MDX formatting that are documented at:
Went in and cleaned up the markdown formatting - mostly the tags on links and indented code highlighting formatting.The build process was also failing due to some errors defining text wrapped in {}
๐๐ผ
Error: Failed to compile due to Webpack errors.
Error: Docusaurus server-side rendering could not render static page with path /docs/editors/git because of error: stash_number is not defined
Error: Docusaurus server-side rendering could not render static page with path /docs/lang/Rust because of error: url is not defined
Error: Docusaurus server-side rendering could not render static page with path /docs/shell/zsh because of error: bz2 is not defined
Error: Docusaurus server-side rendering could not render static page with path /lists/tweets_follow because of error: SoftwareHardwareDeveloperDesignerMakerInventor is not defined
at /Users/david/Sites/daw_til/node_modules/@docusaurus/core/lib/webpack/utils.js:207:24
at /Users/david/Sites/daw_til/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/david/Sites/daw_til/node_modules/webpack/lib/MultiCompiler.js:491:6)
at process.processTicksAndRejections (node:internal/process/task_queues:77:11)
}
[INFO] Docusaurus version: 3.0.0
Node version: v18.12.1
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.
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 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
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
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
# 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
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
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 rm'd -
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
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 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 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/... 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/ instead. It required a bit of cleanup in the Markdown to do so. See: https://davidawindham.com/til/help
05/02/2017
While working on another project yesterday afternoon, I ran into set of documentation (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, 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.
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/docsifyjs/docsify/
- the current Gitbook Search Plugin 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
- gitbook-prism-plugin has an outdated version of prism.
- forked pkg to https://www.npmjs.com/package/gitbook-plugin-prism-dw
- add "gitbook-plugin-prism-dw": "^2.4.1" to pkg.json
migrateโ
# 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:โ
{
"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"
}
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โ
Some content with Markdown syntax
. Check this api
.
Mermaidโ
Creating Docsโ
Create a Markdown file in /docs/doc.md
Add to sidebars.js
Meta Data using Front Matterโ
---
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
[Create a page](/create-a-page)
[Create a page](./create-a-page.md)
Gitbook:โ
https://github.com/GitbookIO/gitbook
https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md
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 Markdown Cheatsheet
Headersโ
# h1
## h2
### h3
#### h4
##### h5
###### h6
Header 1
========
Header 2
--------
Emphasisโ
*italic*
_italic_
**bold**
__bold__
***bold italic***
___bold italic___
~~strikethrough~~
`code`
Listsโ
* Item 1
* Item 2
- Item 1
- Item 2
- [ ] Checkbox off
- [x] Checkbox on
1. Item 1
2. Item 2
Linksโ
[link](http://google.com)
[link][google]
[google]: http://google.com
<http://google.com>
Imagesโ
![Image alt text](/path/to/img.jpg)
![Image alt text](/path/to/img.jpg "title")
![Image alt text][img]
[img]: http://foo.com/img.jpg
Codeโ
4 space indent
makes a code block
```
code fences
```
```js
codeFences.withLanguage()
```
Blockquotesโ
> This is
> a blockquote
>
> > Nested
> > Blockquote
Horizontal lineโ
----
****
Tablesโ
| Column 1 Heading | Column 2 Heading |
| ---------------- | ---------------- |
| Some content | Other content |
Column 1 Heading | Column 2 Heading
--- | ---
Some content | Other content