Merge pull request #71 from justyns/mkdocs

Switch documentation to a combination of silverbullet-pub and mkdocs

.github/workflows/gh-pages-docs.yml

@@ -48,12 +48,23 @@ 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
+          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/
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./docs/_public
+          # path: ./docs/_public
+          path: ./site
 
   # Deployment job
   deploy:

.gitignore

@@ -11,4 +11,5 @@ docs/Library/Core
 !docs/_plug
 SECRETS.md
 cov_profile
-test?space*
+test?space*
+site/

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,14 +28,14 @@ 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
 
 ```query
 page
 where name =~ /^Library\/AICore\/Space Script/
-render [[Library/Core/Query/Template]]
+render [[Library/AIDocs/Query/AI Template]]
 ```
 

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
@@ -72,6 +73,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)

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."
----
+---
+
+> **warning**: Deprecated. Use [[Templated Prompts]] instead.

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.
 

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."
----
+---
+
+> **warning**: Deprecated. Use [[Templated Prompts]] instead.

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."
----
+---
+
+```template
+{{@page.commandSummary}}
+```

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."
----
+---
+
+```template
+{{@page.commandSummary}}
+```

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."
----
+---
+
+```template
+{{@page.commandSummary}}
+```

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."
----
+---
+
+> **warning**: Deprecated. Use [[Templated Prompts]] instead.

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."
----
+---
+
+> **warning**: Deprecated. Use [[Templated Prompts]] instead.

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."
----
+---
+
+```template
+{{@page.commandSummary}}
+```

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).
+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.

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

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}}

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.
 

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.
 

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

mkdocs.yml

@@ -0,0 +1,93 @@
+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
+    - navigation.path
+    - navigation.indexes
+    - content.action.edit
+    - content.code.copy
+    - content.code.annotate
+    - search.suggest
+    - search.highlight
+    - search.share
+
+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:
+  - 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
+  # - 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
+  - Configuration:
+    - Configuration.md
+    - Configuration
+  - AI Core Library.md
+  - Templated Prompts.md
+  - Commands:
+    - Commands
+  - Providers:
+    - Providers
+  - Changelog.md
+  - Development.md

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