feat: add versioned documentation with Docusaurus #1079
Conversation
- Snapshot docs at v2.9.4 as stable version - Configure version dropdown in navbar - Current docs become 'Next' with unreleased banner - Document versioning workflow in AGENTS.md
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThis PR establishes documentation versioning infrastructure for the QuickAdd plugin using Docusaurus. It introduces v2.9.4 as the first released version, marks "next" as the current development branch, and includes comprehensive documentation for v2.9.4 spanning API references, feature guides, examples, and advanced topics. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
quickadd/docs/docusaurus.config.js
Lines 90 to 93 in ccc6667
Make Examples navbar link version-aware
Because this commit introduces versioned docs with the current version served at /docs/next/, the hard-coded navbar link to: '/docs/Examples/Macro_BookFinder' will always jump users to the stable 2.9.4 docs even when they are browsing “Next”. That’s a regression in navigation context: users reading unreleased docs will click “Examples” and land on outdated content. Consider switching this item to a docs link (e.g., type: 'doc' with docId: 'Examples/Macro_BookFinder', or set docsVersion: 'current') so it stays within the selected version.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🤖 Fix all issues with AI agents
In `@docs/versioned_docs/version-2.9.4/Choices/CaptureChoice.md`:
- Line 19: In docs/versioned_docs/version-2.9.4/CaptureChoice.md replace all
occurrences of the absolute link "/FormatSyntax.md" with a relative doc-to-doc
link "../FormatSyntax.md" so Docusaurus can rewrite them to the correct version;
search for the literal "/FormatSyntax.md" instances in CaptureChoice.md and
update each one to "../FormatSyntax.md".
In
`@docs/versioned_docs/version-2.9.4/Examples/Macro_ChangePropertyInDailyNotes.md`:
- Around line 21-23: Replace the Moment.js week-year token with the calendar
year in the date format used to build dailyJournalFilePath: update the format
call in the date assignment (the window.moment().format(...) that populates the
date variable) to use "YYYY-MM-DD - ddd MMM D" instead of "gggg-MM-DD - ddd MMM
D" so filenames use the actual calendar year.
In `@docs/versioned_docs/version-2.9.4/Examples/Macro_LogBookToDailyJournal.md`:
- Around line 13-19: The code uses app.plugins... but never defines app in
scope; destructure app from params alongside quickAddApi to fix the runtime
error (e.g., include app in the existing destructuring that extracts
quickAddApi/inputPrompt), then use app.plugins.plugins["metaedit"].api.update as
before; update the destructuring line that currently reads const { quickAddApi:
{ inputPrompt }, } = params; to also extract app so update() can be accessed
without ReferenceError.
In
`@docs/versioned_docs/version-2.9.4/Examples/Macro_MoveNotesWithATagToAFolder.md`:
- Around line 34-36: The example uses the non-existent String.prototype.contains
on the loop variable in cache.forEach; change the conditional from
key.contains("template") to key.includes("template") so the check uses the
correct JavaScript method (update the code in the cache.forEach callback where
key.contains is used, leaving the surrounding logic with
app.metadataCache.getCache(key) intact).
In
`@docs/versioned_docs/version-2.9.4/Examples/Template_AutomaticBookNotesFromReadwise.md`:
- Around line 99-102: The example uses a non-existent String.prototype.contains
in the books.find predicate; update the predicate to use
String.prototype.includes by changing the check in the books.find callback (the
expression referencing b.title and bookTitle) to use .includes on the lowercased
title (i.e., b.title.toLowerCase().includes(bookTitle.toLowerCase())) so the
lookup works without throwing.
- Around line 175-186: The function formatDailyQuote is returning the array
variable quote inside a template literal which inserts commas; convert the quote
array to a single string (e.g., join with "\n") before concatenation and then
append the attr string so the returned value is properly formatted; update the
return in formatDailyQuote to use the joined quote (and ensure attr includes the
leading newline) rather than interpolating the array directly.
- Around line 220-235: getAllHighlights currently returns an array of arrays
because it maps each apiGet response to hl.results; change the return to a
flattened array so callers get a single list. In the getAllHighlights function,
after awaiting Promise.all(promises) (the variable allHighlights), merge the
nested results (e.g., use Array.prototype.flat() or
Array.prototype.concat.apply/Array.prototype.reduce) and return that flattened
array instead of the nested array of results.
- Around line 188-205: textFormatter uses sourceNote without guarding against
undefined, causing .includes to throw; update textFormatter so sourceNote is
normalized or checked before use (e.g., set a default empty string at the start
of textFormatter or replace calls with (sourceNote || "").includes(...)); ensure
both the .map callback (where it checks sourceNote.includes(".h1")) and the
later conditional (if (sourceNote.includes(".h1") || sourceNote == "" ||
!sourceNote)) use the safe-guarded form or the normalized variable to avoid
runtime errors.
In `@docs/versioned_docs/version-2.9.4/index.md`:
- Line 51: The markdown links in versioned_docs refer to non-relative targets
(e.g., "docs/QuickAddAPI.md", "docs/FormatSyntax.md", "docs/InlineScripts.md",
"docs/Choices/MacroChoice.md"); update each to use relative paths appropriate
for this file's folder (for example "./QuickAddAPI.md", "./FormatSyntax.md",
"./InlineScripts.md", and "./Choices/MacroChoice.md" or "../
Choices/MacroChoice.md" depending on the actual relative location) so the links
resolve correctly in the versioned docs.
- Line 47: Update the markdown link that currently points to
"docs/Examples/Macro_MovieAndSeriesScript.md" so it uses the same relative path
style as the other links in this document; specifically replace the link target
for "Macro: Fetching movies and TV shows into your vault" to the corrected
relative path (e.g., "../Examples/Macro_MovieAndSeriesScript.md") so it resolves
correctly from version-2.9.4/index.md.
- Around line 34-47: Replace the absolute paths in the link list in
docs/versioned_docs/version-2.9.4/index.md (the lines containing entries like
"Capture: Add Journal Entry", "Macro: Log book to daily journal", etc.) so each
link uses a relative path (prefix with ./) instead of "docs/Examples/...";
update every occurrence of "docs/Examples/..." to "./Examples/..." to ensure
versioned Docusaurus links resolve correctly.
🟡 Minor comments (16)
docs/versioned_docs/version-2.9.4/Advanced/ObsidianUri.md-7-9 (1)
7-9: Add language identifiers to fenced code blocks.Markdownlint flags these blocks; add a language like
textto satisfy MD040.♻️ Proposed fix
-``` +```text obsidian://quickadd?choice=<YOUR_CHOICE_NAME>[&value-VALUE_NAME=...]@@
-+text
obsidian://quickadd?vault=My%20Vault&choice=Daily%20log&value-contents=Lorem%20ipsum.Also applies to: 27-29
docs/versioned_docs/version-2.9.4/GlobalVariables.md-34-45 (1)
34-45: Add a language identifier to the fenced code block.MD040 requires a language specifier; use
text(oryamlif you prefer).♻️ Proposed fix
-``` +```text Name: MyProjects Value: {{VALUE:Inbox,Work,Personal,Archive}} In a template path: Projects/{{GLOBAL_VAR:MyProjects}}/{{DATE:YYYY}}/ In content: - Project: {{GLOBAL_VAR:MyProjects}} - Created: {{DATE:YYYY-MM-DD}}</details> </blockquote></details> <details> <summary>docs/versioned_docs/version-2.9.4/Examples/Macro_MovieAndSeriesScript.md-7-7 (1)</summary><blockquote> `7-7`: **Use descriptive link text instead of “here/click here.”** This improves accessibility and matches markdownlint expectations. Consider “OMDb API website” and “installation video” instead. Also applies to: 22-24 </blockquote></details> <details> <summary>docs/versioned_docs/version-2.9.4/Examples/Macro_MovieAndSeriesScript.md-56-56 (1)</summary><blockquote> `56-56`: **Fix QuickAdd token spacing in the template example.** `{ { VALUE:Poster } }` won’t render as a QuickAdd token. It should be `{{VALUE:Poster}}`. <details> <summary>🔧 Proposed fix</summary> ```diff -cover: { { VALUE:Poster } } +cover: {{VALUE:Poster}}docs/versioned_docs/version-2.9.4/Examples/Macro_MovieAndSeriesScript.md-79-105 (1)
79-105: Replace hard tabs in the JSON snippet with spaces.Tabs trigger markdownlint and can render inconsistently across viewers.
🔧 Proposed fix
- "Title": "Arcane", + "Title": "Arcane",docs/versioned_docs/version-2.9.4/Examples/Capture_FetchTasksFromTodoist.md-51-53 (1)
51-53: Wrap the bare URL to satisfy markdownlint (MD034).Line 53 uses a bare URL; this will fail linting. Use a markdown link instead.
🛠️ Suggested fix
-https://user-images.githubusercontent.com/29108628/123511101-bde4a100-d67f-11eb-90c1-5bd146c5d0f2.mp4 +[Installation video](https://user-images.githubusercontent.com/29108628/123511101-bde4a100-d67f-11eb-90c1-5bd146c5d0f2.mp4)docs/versioned_docs/version-2.9.4/FormatSyntax.md-10-10 (1)
10-10: Escape pipes in table cell to avoid broken rendering.The
|inside the code span splits the table into extra columns. Escaping fixes the rendering.🛠️ Suggested fix
-| `{{VDATE:<variable name>, <date format>\|<default>}}` | Same as above, but with a default value. If you leave the prompt empty, the default value will be used instead. Example: `{{VDATE:date,YYYY-MM-DD\|today}}` will use "today" if no input is provided. Default values can be any natural language date like "tomorrow", "next monday", "+7 days", etc. **Note:** If your date format contains pipe characters (`|`), you'll need to escape them as `\|` or use square brackets like `[|]` to avoid conflicts with the default value separator. | +| `{{VDATE:<variable name>, <date format>\|<default>}}` | Same as above, but with a default value. If you leave the prompt empty, the default value will be used instead. Example: `{{VDATE:date,YYYY-MM-DD\|today}}` will use "today" if no input is provided. Default values can be any natural language date like "tomorrow", "next monday", "+7 days", etc. **Note:** If your date format contains pipe characters (`\|`), you'll need to escape them as `\|` or use square brackets like `[|]` to avoid conflicts with the default value separator. |docs/versioned_docs/version-2.9.4/Examples/Template_AutomaticBookNotesFromReadwise.md-31-251 (1)
31-251: Replace hard tabs with spaces in the JS block.
MD010 flags many lines; consistent spaces improve rendering in markdown.docs/versioned_docs/version-2.9.4/Examples/Capture_AddJournalEntry.md-13-15 (1)
13-15: Add a language to the fenced code block.
MD040 requires a language hint.✅ Suggested tweak
-``` +```md - {{DATE:HH:mm}} {{VALUE}}\n</details> </blockquote></details> <details> <summary>docs/versioned_docs/version-2.9.4/Examples/Template_AutomaticBookNotesFromReadwise.md-22-22 (1)</summary><blockquote> `22-22`: **Remove spaces inside inline code span.** MD038 flags the extra space inside ``{ ``. <details> <summary>✅ Suggested tweak</summary> ```diff -Notably, the book's name would be the one selected. I have chosen to write prepend a `{ ` before it, as I use this to denote literature notes in my vault. +Notably, the book's name would be the one selected. I have chosen to prepend a `{` before it, as I use this to denote literature notes in my vault.docs/versioned_docs/version-2.9.4/Examples/Template_AutomaticBookNotesFromReadwise.md-9-12 (1)
9-12: Use descriptive link text instead of “here”.
Helps accessibility and meets MD059.✅ Suggested tweak
-Then, in the script, you see the `YOUR_READWISE_TOKEN`, which is where you'll want to insert your Readwise token (find it [here](https://readwise.io/access_token)). +Then, in the script, you see the `YOUR_READWISE_TOKEN`, which is where you'll want to insert your Readwise token (find it on the [Readwise access token page](https://readwise.io/access_token)).docs/versioned_docs/version-2.9.4/InlineScripts.md-8-13 (1)
8-13: Specify a language for the outer fenced block.
MD040 flags the outer fence; usemd(ortext) to describe the wrapper.✅ Suggested tweak
-```` +````md ```js quickadd const input = await this.quickAddApi.inputPrompt("✍"); return `Input given: ${input}`;-
+</details> </blockquote></details> <details> <summary>docs/versioned_docs/version-2.9.4/index.md-8-8 (1)</summary><blockquote> `8-8`: **Remove extra space before the period.** There's an extraneous space before the period. <details> <summary>Suggested fix</summary> ```diff -**This plugin is in the community plugin browser in Obsidian**. You can search for it and install it there . +**This plugin is in the community plugin browser in Obsidian**. You can search for it and install it there.docs/versioned_docs/version-2.9.4/index.md-18-18 (1)
18-18: Fix typo: "your want" → "you want".Grammar error flagged by static analysis.
Suggested fix
-- [Macro Choice](./Choices/MacroChoice) - Macros to augment your workflow. Use the full power of Javascript programming language and Obsidian functions to do anything your want. E.g. [create a personal movie database](./Examples/Macro_MovieAndSeriesScript) by writing a movie name and getting the movie notes fully customized and filled with correct film's up-to-date data. +- [Macro Choice](./Choices/MacroChoice) - Macros to augment your workflow. Use the full power of Javascript programming language and Obsidian functions to do anything you want. E.g. [create a personal movie database](./Examples/Macro_MovieAndSeriesScript) by writing a movie name and getting the movie notes fully customized and filled with correct film's up-to-date data.docs/versioned_docs/version-2.9.4/QuickAddAPI.md-126-137 (1)
126-137: Replace hard tabs with spaces for consistency.The linter correctly flags hard tabs in this code example. Markdown documents should use spaces for consistent rendering across different viewers and editors.
📝 Proposed fix
try { - const name = await quickAddApi.inputPrompt( - "What's your name?", - "Enter your full name", - "John Doe" - ); - console.log(`Hello, ${name}!`); + const name = await quickAddApi.inputPrompt( + "What's your name?", + "Enter your full name", + "John Doe" + ); + console.log(`Hello, ${name}!`); } catch (error) { - if (error?.name === "MacroAbortError") { - // Optional: perform cleanup before QuickAdd aborts the macro - return; - } - throw error; + if (error?.name === "MacroAbortError") { + // Optional: perform cleanup before QuickAdd aborts the macro + return; + } + throw error; }docs/versioned_docs/version-2.9.4/QuickAddAPI.md-590-600 (1)
590-600: Add normalizePath wrapper to the folder existence check.The
app.vault.adapter.exists()method is valid, but the code should normalize the path first. The Obsidian API documentation specifies that paths must be normalized before passing toexists(). Update line 592 to:const folderExists = await app.vault.adapter.exists(normalizePath(folder));Ensure
normalizePathis imported from theobsidianpackage.
🧹 Nitpick comments (7)
docs/versioned_docs/version-2.9.4/Choices/TemplateChoice.md (1)
16-18: Reduce repeated sentence openings for readability.Three consecutive sentences start with “If you specify…”, which reads a bit repetitive. Consider rephrasing one of them.
docs/versioned_docs/version-2.9.4/FormatSyntax.md (1)
21-21: Use descriptive link text instead of “here.”The link text isn’t descriptive; consider naming it after the feedback issue.
🛠️ Suggested fix
--leave your thoughts [here](https://github.com/chhoumann/quickadd/issues/337). +-leave your thoughts on [issue `#337`](https://github.com/chhoumann/quickadd/issues/337).docs/versioned_docs/version-2.9.4/Choices/CaptureChoice.md (1)
46-54: Adjust nested list indentation for consistency.The nested list items use 4-space indentation, but the project's markdownlint configuration expects 2 spaces for nested lists. While both are valid Markdown, consistency with the linting rules improves maintainability.
♻️ Adjust indentation to 2 spaces
- **Enabled (requires active file)** – keeps the legacy behavior and throws an error if no note is focused - - **Enabled (skip if no active file)** – inserts the link when possible and silently drops `{{LINKCURRENT}}` if nothing is open - - **Disabled** – never append a link + - **Enabled (requires active file)** – keeps the legacy behavior and throws an error if no note is focused + - **Enabled (skip if no active file)** – inserts the link when possible and silently drops `{{LINKCURRENT}}` if nothing is open + - **Disabled** – never append a link When either enabled mode is selected, you can choose where the link is placed: - - **Replace selection** - Replaces any selected text with the link (default) - - **After selection** - Preserves selected text and places the link after it - - **End of line** - Places the link at the end of the current line - - **New line** - Places the link on a new line below the cursor + - **Replace selection** - Replaces any selected text with the link (default) + - **After selection** - Preserves selected text and places the link after it + - **End of line** - Places the link at the end of the current line + - **New line** - Places the link on a new line below the cursordocs/versioned_docs/version-2.9.4/Examples/Macro_BookFinder.md (1)
14-14: Consider using Markdown link syntax for consistency.The HTML anchor tag with the
downloadattribute works but is inconsistent with Markdown conventions used throughout the documentation. Converting to standard Markdown link syntax would improve consistency.♻️ Convert to Markdown link
-You can find the script <a href="/scripts/BookFinder.js" download>here</a>. +You can find the script [here](/scripts/BookFinder.js).Note: The
downloadattribute functionality may need to be handled differently if required, as standard Markdown links don't support it directly.docs/versioned_docs/version-2.9.4/Misc/AHK_OpenQuickAddFromDesktop.md (1)
25-25: Format URL as Markdown link.The bare URL should be formatted as a proper Markdown link for consistency with linting rules and better accessibility.
♻️ Convert to Markdown link
-Here's a guide to what the `!^+` mean, and how you can customize it: https://www.autohotkey.com/docs/Hotkeys.htm +Here's a [guide to AutoHotkey hotkey syntax](https://www.autohotkey.com/docs/Hotkeys.htm) that explains what the `!^+` symbols mean and how you can customize them.docs/versioned_docs/version-2.9.4/AIAssistant.md (2)
70-74: Consider adding a language identifier to fenced code blocks.Adding a language identifier (e.g.,
textoryaml) improves accessibility and may help with syntax highlighting consistency. Flagged by markdownlint.Suggested fix
-``` +```text Name: Ollama URL: http://localhost:11434/v1 Api Key: (empty)</details> --- `83-91`: **Consider adding a language identifier to this code block as well.** Same suggestion for consistency. <details> <summary>Suggested fix</summary> ```diff -``` +```text Name: Gemini URL: https://generativelanguage.googleapis.com API Key: (AI Studio API key) Models (add one or more): - gemini-1.5-pro (Max Tokens: 1000000) - gemini-1.5-flash (Max Tokens: 1000000) - gemini-1.5-flash-8b (Max Tokens: 1000000)</details> </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Summary
Adds versioned documentation support using Docusaurus's built-in versioning feature. This addresses the issue where docs were ahead of releases, confusing users.
Changes
docs/docs/becomes "Next 🚧" with an unreleased warning bannerHow it works
/docs/→ shows stable 2.9.4 docs (default)/docs/next/→ shows unreleased features with a bannerFor future releases
Then update
docusaurus.config.jsto setlastVersionto the new version.Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.