From 04621f568b8c77fae4d7a016f79dbf4b794205e3 Mon Sep 17 00:00:00 2001
From: Justyn Shull <git@justyn.io>
Date: Mon, 16 Sep 2024 00:57:14 -0500
Subject: [PATCH 1/2] Switch documentation to a combination of silverbullet-pub
 and mkdocs

---
 .github/workflows/gh-pages-docs.yml      | 11 +++-
 .gitignore                               |  3 +-
 docs/AI Core Library.md                  |  4 +-
 docs/Changelog.md                        |  1 +
 docs/Installation.md                     |  2 +-
 docs/Library/AIDocs/Query/AI Template.md |  8 +++
 docs/Quick Start.md                      |  2 +-
 docs/mkdocs-sb.py                        | 45 ++++++++++++++
 mkdocs.yml                               | 76 ++++++++++++++++++++++++
 render-docs.sh                           | 15 +++++
 10 files changed, 161 insertions(+), 6 deletions(-)
 create mode 100644 docs/Library/AIDocs/Query/AI Template.md
 create mode 100644 docs/mkdocs-sb.py
 create mode 100644 mkdocs.yml
 create mode 100755 render-docs.sh

diff --git a/.github/workflows/gh-pages-docs.yml b/.github/workflows/gh-pages-docs.yml
index e1982ad..21788c4 100644
--- a/.github/workflows/gh-pages-docs.yml
+++ b/.github/workflows/gh-pages-docs.yml
@@ -48,7 +48,16 @@ jobs:
 
       - name: Build Docs site
         run: |
-          SB_DB_BACKEND=memory deno run --unstable-kv --unstable-worker-options -A https://edge.silverbullet.md/silverbullet.js plug:run docs/ pub.publishAll && cp -v docs/style.css docs/_public/
+          ./render-docs.sh
+
+      - name: Run mkdocs
+        run: |
+          pip install mkdocs-material==9.5.34
+          pip install mkdocs-git-revision-date-localized-plugin==1.2.9
+          pip install mdx_truly_sane_lists==1.3
+          mkdocs build
+          mkdir -pv site/Library/AICore
+          cp -Rv docs/Library/AICore/* site/Library/AICore/
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
diff --git a/.gitignore b/.gitignore
index a86ef55..0b7f0e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,4 +11,5 @@ docs/Library/Core
 !docs/_plug
 SECRETS.md
 cov_profile
-test?space*
\ No newline at end of file
+test?space*
+site/
\ No newline at end of file
diff --git a/docs/AI Core Library.md b/docs/AI Core Library.md
index 51f9728..a1259c7 100644
--- a/docs/AI Core Library.md	
+++ b/docs/AI Core Library.md	
@@ -18,7 +18,7 @@ libraries:
 - import: "[[!ai.silverbullet.md/Library/AICore/*]]"
 ```
 
-Once added, run the {[Libraries: Update]} command to download the libraries. **Note**: This needs to run from a client that is not in sync-mode due to CORs issues.
+Once added, run the {[Libraries: Update]} command to download the libraries.
 
 
 The included templates, prompts, and space scripts are briefly described below. Please consider [contributing](https://github.com/justyns/silverbullet-ai) any templates or prompts you find useful.
@@ -28,7 +28,7 @@ The included templates, prompts, and space scripts are briefly described below.
 ```query
 template
 where name =~ /^Library\/AICore/
-render [[Library/Core/Query/Template]]
+render [[Library/AIDocs/Query/AI Template]]
 ```
 
 # Included Space Script
diff --git a/docs/Changelog.md b/docs/Changelog.md
index 7d7dfa0..96419a9 100644
--- a/docs/Changelog.md
+++ b/docs/Changelog.md
@@ -72,6 +72,7 @@ This page is a brief overview of each version.
 ---
 ## 0.0.11
 - Support for custom chat message enrichment functions, see [[Configuration/Custom Enrichment Functions]]
+
 ---
 ## 0.0.10
 - Add WIP docs and docs workflow by [@justyns](https://github.com/justyns) in [#20](https://github.com/justyns/silverbullet-ai/pull/20)
diff --git a/docs/Installation.md b/docs/Installation.md
index 0b79d61..b9450e0 100644
--- a/docs/Installation.md
+++ b/docs/Installation.md
@@ -10,7 +10,7 @@ For in-development code from the main branch:
 - github:justyns/silverbullet-ai/silverbullet-ai.plug.js
 ```
 
-For the latest "release" code, mostly also still in development for now:
+For the latest [release](https://github.com/justyns/silverbullet-ai/releases) version:
 
 ```yaml
 - ghr:justyns/silverbullet-ai/0.3.2
diff --git a/docs/Library/AIDocs/Query/AI Template.md b/docs/Library/AIDocs/Query/AI Template.md
new file mode 100644
index 0000000..ed181ff
--- /dev/null
+++ b/docs/Library/AIDocs/Query/AI Template.md	
@@ -0,0 +1,8 @@
+---
+tags: template
+---
+
+* [[{{ref}}]] {{#if aiprompt}}{{aiprompt.description}}{{else}}{{description}}{{/if}}
+{{#if aiprompt.usage}}
+  * **Usage:** {{aiprompt.usage}}
+{{/if}}
diff --git a/docs/Quick Start.md b/docs/Quick Start.md
index 2fba48b..e862b08 100644
--- a/docs/Quick Start.md	
+++ b/docs/Quick Start.md	
@@ -51,7 +51,7 @@ ai:
 
 Run `AI: Select Text Model from Config`, choose one of the models you just configured.
 
-> **note** If you only have one model configured, it will be selected automatically.
+> **note**: If you only have one model configured, it will be selected automatically.
 
 Open a new note, run [[Commands/AI: Chat on current page]] or press (CTRL|CMD)+SHIFT+ENTER to start a chat session.
 
diff --git a/docs/mkdocs-sb.py b/docs/mkdocs-sb.py
new file mode 100644
index 0000000..a73860f
--- /dev/null
+++ b/docs/mkdocs-sb.py
@@ -0,0 +1,45 @@
+import logging
+import re
+import mkdocs.plugins
+import os.path
+
+log = logging.getLogger('mkdocs')
+
+root_dir = os.path.abspath(os.path.join(os.path.dirname(__file__)))
+
+def find_target_file(root_dir, link):
+    # Implement the logic to find the target file
+    # This is a placeholder implementation
+    potential_path = os.path.join(root_dir, f"{link}.md")
+    return potential_path if os.path.exists(potential_path) else None
+
+def replace_wiki_link(match, root_dir, page):
+    # Wiki links in silverbullet are always relative from the root space directory
+    link = match.group(1).strip()
+    alias = match.group(2).strip() if len(match.groups()) > 1 and match.group(2) else os.path.basename(link)
+    target_path = find_target_file(root_dir, link)
+    log.info(f"target_path: {target_path}")
+    log.info(f"page.file.abs_src_path: {page.file.abs_src_path}")
+    if target_path:
+        relative_path = os.path.relpath(target_path, os.path.dirname(os.path.dirname(page.file.abs_src_path)))
+        log.info(f"wiki link: {link} -> {relative_path}")
+        return f'[{alias}]({relative_path})'
+    else:
+        log.warning(f"Target file not found for wiki link: {link}")
+        return f'[{alias}]({link}.md)'
+
+def convert_admonitions(markdown):
+    # Convert blockquotes with bold headers to MkDocs-style admonitions
+    # Matches lines starting with "> **Header**:" and captures the header and content
+    return re.sub(r'^> \*\*([\w\s]+)\*\*:\s*(.*(?:\n(?!>).*)*)', r'!!! \1\n\n    \2', markdown, flags=re.MULTILINE)
+
+def process_links(markdown, root_dir, page):
+    # Convert wiki-style links [[Page]] or [[Page|Alias]] to Markdown links
+    # Captures the page name and optional alias, then calls replace_wiki_link function
+    return re.sub(r'\[\[([^|\]]+)(?:\|([^\]]+))?\]\]', lambda m: replace_wiki_link(m, root_dir, page), markdown)
+
+@mkdocs.plugins.event_priority(-50)
+def on_page_markdown(markdown, page, **kwargs):
+    markdown = process_links(markdown, root_dir, page)
+    markdown = convert_admonitions(markdown)
+    return markdown
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..0deb261
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,76 @@
+site_name: Silverbullet AI Plug
+repo_url: https://github.com/justyns/silverbullet-ai
+edit_uri: edit/main/docs/
+docs_dir: docs/_public
+theme:
+  name: material
+  color_mode: auto
+  user_color_mode_toggle: true
+  palette: 
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.footer
+    - content.action.edit
+    - content.code.copy
+    - content.code.annotate
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.keys
+  - admonition
+  - pymdownx.details
+  - footnotes
+  # - wikilinks
+  # - def_list
+  - mdx_truly_sane_lists
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/justyns/silverbullet-ai
+
+# plugins:
+  # TODO: Doesn't really work with pub since it creates new files
+  # - git-revision-date-localized:
+  #     enable_creation_date: true
+  # - optimize
+
+hooks:
+  - docs/mkdocs-sb.py
+
+watch:
+  - docs/_public
+  - docs/mkdocs-sb.py
+  - mkdocs.yml
+
+exclude_docs: |
+  SETTINGS.md
+  PLUGS.md
+  SECRETS.md
+  template/
+  Library/
+  Features.md
+  Commands.md
+
+nav:
+  - Home: index.md
+  - Quick Start.md
+  - Installation.md
+  - Changelog.md
\ No newline at end of file
diff --git a/render-docs.sh b/render-docs.sh
new file mode 100755
index 0000000..a56a6cf
--- /dev/null
+++ b/render-docs.sh
@@ -0,0 +1,15 @@
+#!env bash
+
+# Publish using the pub plugin to render code blocks/queries/etc
+SB_DB_BACKEND=memory deno run --unstable-kv --unstable-worker-options -A https://edge.silverbullet.md/silverbullet.js plug:run docs/ pub.publishAll && cp -v docs/style.css docs/_public/
+
+# Delete html files
+find docs/_public -type f -name \*.html -delete
+find docs/_public -type d -empty -delete
+
+# Delete extra sb-specific files
+
+rm -fv \
+    docs/_public/SETTINGS.md \
+    docs/_public/PLUGS.md \
+    docs/_public/*.css
\ No newline at end of file

From 49b9d9d45c3cb9e5ad0983f499506c27e7e00501 Mon Sep 17 00:00:00 2001
From: Justyn Shull <git@justyn.io>
Date: Mon, 16 Sep 2024 01:45:57 -0500
Subject: [PATCH 2/2] Update command descriptions, deprecate a few

---
 .github/workflows/gh-pages-docs.yml           |  4 +++-
 docs/AI Core Library.md                       |  2 +-
 docs/Changelog.md                             |  1 +
 .../AI: Call OpenAI with Note as context.md   |  4 +++-
 .../Commands/AI: Generate Note FrontMatter.md |  2 +-
 docs/Commands/AI: Insert Summary.md           |  4 +++-
 .../AI: Select Embedding Model from Config.md |  6 +++++-
 .../AI: Select Image Model from Config.md     |  6 +++++-
 .../AI: Select Text Model from Config.md      |  6 +++++-
 ...sponse with selection or note as prompt.md |  4 +++-
 .../AI: Summarize Note and open summary.md    |  4 +++-
 .../Commands/AI: Test Embedding Generation.md |  6 +++++-
 docs/Development.md                           | 18 +++++++++++++++-
 docs/Library/AIDocs/Query/AI Template.md      |  2 +-
 docs/Templated Prompts.md                     |  2 +-
 mkdocs.yml                                    | 21 +++++++++++++++++--
 16 files changed, 76 insertions(+), 16 deletions(-)

diff --git a/.github/workflows/gh-pages-docs.yml b/.github/workflows/gh-pages-docs.yml
index 21788c4..10df75c 100644
--- a/.github/workflows/gh-pages-docs.yml
+++ b/.github/workflows/gh-pages-docs.yml
@@ -55,6 +55,7 @@ jobs:
           pip install mkdocs-material==9.5.34
           pip install mkdocs-git-revision-date-localized-plugin==1.2.9
           pip install mdx_truly_sane_lists==1.3
+          pip install mkdocs-include-dir-to-nav==1.2.0
           mkdocs build
           mkdir -pv site/Library/AICore
           cp -Rv docs/Library/AICore/* site/Library/AICore/
@@ -62,7 +63,8 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./docs/_public
+          # path: ./docs/_public
+          path: ./site
 
   # Deployment job
   deploy:
diff --git a/docs/AI Core Library.md b/docs/AI Core Library.md
index a1259c7..9bc4a3d 100644
--- a/docs/AI Core Library.md	
+++ b/docs/AI Core Library.md	
@@ -36,6 +36,6 @@ render [[Library/AIDocs/Query/AI Template]]
 ```query
 page
 where name =~ /^Library\/AICore\/Space Script/
-render [[Library/Core/Query/Template]]
+render [[Library/AIDocs/Query/AI Template]]
 ```
 
diff --git a/docs/Changelog.md b/docs/Changelog.md
index 96419a9..4ca9dda 100644
--- a/docs/Changelog.md
+++ b/docs/Changelog.md
@@ -29,6 +29,7 @@ This page is a brief overview of each version.
 - AICore Library: Add `aiSplitTodo` slash command and [[^Library/AICore/AIPrompt/AI Split Task]] templated prompt to split a task into smaller subtasks.
 - AICore Library: Add template prompts for rewriting text, mostly as a demo for the `replace-smart` insertAt option.
 - Remove need for duplicate `description` frontmatter field for templated prompts.
+- Revamp docs website to use mkdocs (and mkdocs-material) in addition to silverbullet-pub to handle the silverbullet-specific things like templates/queries.
 
 ---
 ## 0.3.2
diff --git a/docs/Commands/AI: Call OpenAI with Note as context.md b/docs/Commands/AI: Call OpenAI with Note as context.md
index 5e3e42a..32dc871 100644
--- a/docs/Commands/AI: Call OpenAI with Note as context.md	
+++ b/docs/Commands/AI: Call OpenAI with Note as context.md	
@@ -4,4 +4,6 @@ commandName: "AI: Call OpenAI with Note as context"
 commandSummary: "Prompts the user for a custom prompt to send to the LLM.  If the user has text selected, the selected text is used as the note content.
 If the user has no text selected, the entire note is used as the note content.
 The response is streamed to the cursor position."
----
\ No newline at end of file
+---
+
+> **warning**: Deprecated. Use [[Templated Prompts]] instead.
\ No newline at end of file
diff --git a/docs/Commands/AI: Generate Note FrontMatter.md b/docs/Commands/AI: Generate Note FrontMatter.md
index 5663c3f..078946d 100644
--- a/docs/Commands/AI: Generate Note FrontMatter.md	
+++ b/docs/Commands/AI: Generate Note FrontMatter.md	
@@ -5,7 +5,7 @@ commandSummary: "Extracts important information from the current note and conver
 to frontmatter attributes."
 ---
 
-**Experimental**: This is new and not well-tested.  Please submit feedback if you have ideas for making it better.
+> **note**: **Experimental**: This is new and not well-tested.  Please submit feedback if you have ideas for making it better.
 
 This command will attempt to extract useful information from a note and then generate frontmatter attributes for that note.
 
diff --git a/docs/Commands/AI: Insert Summary.md b/docs/Commands/AI: Insert Summary.md
index 96f4546..1fbbf17 100644
--- a/docs/Commands/AI: Insert Summary.md	
+++ b/docs/Commands/AI: Insert Summary.md	
@@ -3,4 +3,6 @@ tags: commands
 commandName: "AI: Insert Summary"
 commandSummary: "Uses a built-in prompt to ask the LLM for a summary of either the entire note, or the selected
 text.  Inserts the summary at the cursor's position."
----
\ No newline at end of file
+---
+
+> **warning**: Deprecated. Use [[Templated Prompts]] instead.
\ No newline at end of file
diff --git a/docs/Commands/AI: Select Embedding Model from Config.md b/docs/Commands/AI: Select Embedding Model from Config.md
index f7c9bf4..54edad4 100644
--- a/docs/Commands/AI: Select Embedding Model from Config.md	
+++ b/docs/Commands/AI: Select Embedding Model from Config.md	
@@ -2,4 +2,8 @@
 tags: commands
 commandName: "AI: Select Embedding Model from Config"
 commandSummary: "Prompts the user to select an embedding model from the configured models."
----
\ No newline at end of file
+---
+
+```template
+{{@page.commandSummary}}
+```
\ No newline at end of file
diff --git a/docs/Commands/AI: Select Image Model from Config.md b/docs/Commands/AI: Select Image Model from Config.md
index 22d5116..50d793f 100644
--- a/docs/Commands/AI: Select Image Model from Config.md	
+++ b/docs/Commands/AI: Select Image Model from Config.md	
@@ -2,4 +2,8 @@
 tags: commands
 commandName: "AI: Select Image Model from Config"
 commandSummary: "Prompts the user to select an image model from the configured models."
----
\ No newline at end of file
+---
+
+```template
+{{@page.commandSummary}}
+```
\ No newline at end of file
diff --git a/docs/Commands/AI: Select Text Model from Config.md b/docs/Commands/AI: Select Text Model from Config.md
index 974eb3d..38547f7 100644
--- a/docs/Commands/AI: Select Text Model from Config.md	
+++ b/docs/Commands/AI: Select Text Model from Config.md	
@@ -2,4 +2,8 @@
 tags: commands
 commandName: "AI: Select Text Model from Config"
 commandSummary: "Prompts the user to select a text/llm model from the configured models."
----
\ No newline at end of file
+---
+
+```template
+{{@page.commandSummary}}
+```
\ No newline at end of file
diff --git a/docs/Commands/AI: Stream response with selection or note as prompt.md b/docs/Commands/AI: Stream response with selection or note as prompt.md
index c9a89a2..908e654 100644
--- a/docs/Commands/AI: Stream response with selection or note as prompt.md	
+++ b/docs/Commands/AI: Stream response with selection or note as prompt.md	
@@ -2,4 +2,6 @@
 tags: commands
 commandName: "AI: Stream response with selection or note as prompt"
 commandSummary: "Streams a conversation with the LLM, inserting the responses at the cursor position as it is received."
----
\ No newline at end of file
+---
+
+> **warning**: Deprecated. Use [[Templated Prompts]] instead.
\ No newline at end of file
diff --git a/docs/Commands/AI: Summarize Note and open summary.md b/docs/Commands/AI: Summarize Note and open summary.md
index c8566f2..8c71364 100644
--- a/docs/Commands/AI: Summarize Note and open summary.md	
+++ b/docs/Commands/AI: Summarize Note and open summary.md	
@@ -3,4 +3,6 @@ tags: commands
 commandName: "AI: Summarize Note and open summary"
 commandSummary: "Uses a built-in prompt to ask the LLM for a summary of either the entire note, or the selected
 text.  Opens the resulting summary in a temporary right pane."
----
\ No newline at end of file
+---
+
+> **warning**: Deprecated. Use [[Templated Prompts]] instead.
\ No newline at end of file
diff --git a/docs/Commands/AI: Test Embedding Generation.md b/docs/Commands/AI: Test Embedding Generation.md
index 3e481ae..3404bd9 100644
--- a/docs/Commands/AI: Test Embedding Generation.md	
+++ b/docs/Commands/AI: Test Embedding Generation.md	
@@ -3,4 +3,8 @@ tags: commands
 commandName: "AI: Test Embedding Generation"
 commandSummary: "Function to test generating embeddings.  Just puts the result in the current note, but
 isn't too helpful for most cases."
----
\ No newline at end of file
+---
+
+```template
+{{@page.commandSummary}}
+```
\ No newline at end of file
diff --git a/docs/Development.md b/docs/Development.md
index 2cd7e91..d8a0fcc 100644
--- a/docs/Development.md
+++ b/docs/Development.md
@@ -23,4 +23,20 @@ Then, copy the resulting `.plug.js` file into your space's `_plug` folder. Or bu
 deno task build && cp *.plug.js /my/space/_plug/
 ```
 
-SilverBullet will automatically sync and load the new version of the plug (or speed up this process by running the {[Sync: Now]} command).
\ No newline at end of file
+SilverBullet will automatically sync and load the new version of the plug (or speed up this process by running the {[Sync: Now]} command).
+
+
+## Docs
+
+Documentation is located in the `docs/` directory and rendered using a combination of the [silverbullet-pub plugin](https://github.com/silverbulletmd/silverbullet-pub) and [mkdocs](https://github.com/mkdocs/mkdocs).
+
+To make changes, use silverbullet locally like: `silverbullet docs/`
+
+If you want to see changes in real-time, open up two terminals and run these two commands:
+
+- `mkdocs serve -a localhost:9000`
+- `find docs -name \*.md -type f | egrep -v 'public' | entr bash ./render-docs.sh`
+
+The first starts a local development server of mkdocs. The second uses the [entr](https://github.com/eradman/entr) command to run silverbullet-pub every time a file changes inside the silverbullet docs/ directory.
+
+Markdown files inside of docs/ can also be manually edited using any editor.
\ No newline at end of file
diff --git a/docs/Library/AIDocs/Query/AI Template.md b/docs/Library/AIDocs/Query/AI Template.md
index ed181ff..50d03fa 100644
--- a/docs/Library/AIDocs/Query/AI Template.md	
+++ b/docs/Library/AIDocs/Query/AI Template.md	
@@ -2,7 +2,7 @@
 tags: template
 ---
 
-* [[{{ref}}]] {{#if aiprompt}}{{aiprompt.description}}{{else}}{{description}}{{/if}}
+* **{{ref}}** {{#if aiprompt}}{{aiprompt.description}}{{else}}{{description}}{{/if}}
 {{#if aiprompt.usage}}
   * **Usage:** {{aiprompt.usage}}
 {{/if}}
diff --git a/docs/Templated Prompts.md b/docs/Templated Prompts.md
index 24fa784..23e8c0b 100644
--- a/docs/Templated Prompts.md	
+++ b/docs/Templated Prompts.md	
@@ -3,7 +3,7 @@ tags: sidebar
 navOrder: 20
 ---
 
-**NOTE:** All built-in prompts may be replaced with templated prompts eventually.
+> **note:** All built-in prompts may be replaced with templated prompts eventually.
 
 As of 0.0.6, you can use template notes to create your own custom prompts to send to the LLM.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 0deb261..44fedab 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -21,9 +21,14 @@ theme:
         name: Switch to light mode
   features:
     - navigation.footer
+    - navigation.path
+    - navigation.indexes
     - content.action.edit
     - content.code.copy
     - content.code.annotate
+    - search.suggest
+    - search.highlight
+    - search.share
 
 markdown_extensions:
   - pymdownx.highlight:
@@ -46,7 +51,9 @@ extra:
     - icon: fontawesome/brands/github
       link: https://github.com/justyns/silverbullet-ai
 
-# plugins:
+plugins:
+  - include_dir_to_nav
+  - search
   # TODO: Doesn't really work with pub since it creates new files
   # - git-revision-date-localized:
   #     enable_creation_date: true
@@ -73,4 +80,14 @@ nav:
   - Home: index.md
   - Quick Start.md
   - Installation.md
-  - Changelog.md
\ No newline at end of file
+  - Configuration:
+    - Configuration.md
+    - Configuration
+  - AI Core Library.md
+  - Templated Prompts.md
+  - Commands:
+    - Commands
+  - Providers:
+    - Providers
+  - Changelog.md
+  - Development.md
\ No newline at end of file