Doc #90
Doc #90
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughA new Docusaurus documentation site has been established, featuring a comprehensive configuration for deployment, version management, and internationalization. Key components include a GitHub Actions workflow for publishing to GitHub Pages, a structured sidebar for navigation, and various tutorials for users. Additionally, styling files have been introduced to enhance the visual presentation of the site, alongside TypeScript and Babel configurations to support modern JavaScript development. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant GitHub Actions
participant GitHub Pages
User->>GitHub Actions: Push changes to main branch
GitHub Actions->>GitHub Pages: Deploy static content
GitHub Pages-->>User: Serve updated site
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
Outside diff range, codebase verification and nitpick comments (4)
docs/docs/tutorial-basics/create-a-document.md (1)
1-57: Well-structured tutorial documentThis document is well-structured and provides clear, step-by-step instructions on creating and managing documents in Docusaurus. The use of markdown and JavaScript snippets enhances understanding.
Consider adding a brief introduction or overview at the beginning to set the context for new users.
.github/workflows/doc.yaml (1)
1-43: Robust GitHub Actions workflow for deploymentThis GitHub Actions workflow is well-configured for deploying static content to GitHub Pages. It includes all necessary steps and uses up-to-date actions for each task.
Consider adding comments within the workflow file to explain the purpose of each step, especially for users who may be new to GitHub Actions.
docs/docs/tutorial-basics/markdown-features.mdx (1)
1-152: Content is well-structured and informative.The Markdown and MDX content is well-structured, providing a comprehensive overview of features supported by Docusaurus. The use of informal language ('awesome') is noted but fits the casual tone often used in tech documentation. Consider using a more formal alternative if the documentation targets a more formal audience.
Tools
LanguageTool
[style] ~98-~98: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...erous ::: ``` :::tip My tip Use this awesome feature option ::: :::danger Take car...(AWESOME)
docs/docs/tutorial-basics/create-a-blog-post.md (1)
7-34: Suggestion: Clarify Date in ExampleThe tutorial is clear and well-written. Consider clarifying that the date in the example (
2021-02-28) is arbitrary and should be replaced with the current date when creating a new post.
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files ignored due to path filters (10)
docs/docs/tutorial-extras/img/docsVersionDropdown.pngis excluded by!**/*.pngdocs/docs/tutorial-extras/img/localeDropdown.pngis excluded by!**/*.pngdocs/package-lock.jsonis excluded by!**/package-lock.jsondocs/static/img/docusaurus-social-card.jpgis excluded by!**/*.jpgdocs/static/img/docusaurus.pngis excluded by!**/*.pngdocs/static/img/favicon.icois excluded by!**/*.icodocs/static/img/logo.svgis excluded by!**/*.svgdocs/static/img/undraw_docusaurus_mountain.svgis excluded by!**/*.svgdocs/static/img/undraw_docusaurus_react.svgis excluded by!**/*.svgdocs/static/img/undraw_docusaurus_tree.svgis excluded by!**/*.svg
Files selected for processing (25)
- .github/workflows/doc.yaml (1 hunks)
- docs/.gitignore (1 hunks)
- docs/README.md (1 hunks)
- docs/babel.config.js (1 hunks)
- docs/docs/intro.md (1 hunks)
- docs/docs/tutorial-basics/category.json (1 hunks)
- docs/docs/tutorial-basics/congratulations.md (1 hunks)
- docs/docs/tutorial-basics/create-a-blog-post.md (1 hunks)
- docs/docs/tutorial-basics/create-a-document.md (1 hunks)
- docs/docs/tutorial-basics/create-a-page.md (1 hunks)
- docs/docs/tutorial-basics/deploy-your-site.md (1 hunks)
- docs/docs/tutorial-basics/markdown-features.mdx (1 hunks)
- docs/docs/tutorial-extras/category.json (1 hunks)
- docs/docs/tutorial-extras/manage-docs-versions.md (1 hunks)
- docs/docs/tutorial-extras/translate-your-site.md (1 hunks)
- docs/docusaurus.config.ts (1 hunks)
- docs/package.json (1 hunks)
- docs/sidebars.ts (1 hunks)
- docs/src/components/HomepageFeatures/index.tsx (1 hunks)
- docs/src/components/HomepageFeatures/styles.module.css (1 hunks)
- docs/src/css/custom.css (1 hunks)
- docs/src/pages/index.module.css (1 hunks)
- docs/src/pages/index.tsx (1 hunks)
- docs/src/pages/markdown-page.md (1 hunks)
- docs/tsconfig.json (1 hunks)
Files skipped from review due to trivial changes (10)
- docs/.gitignore
- docs/babel.config.js
- docs/docs/tutorial-basics/category.json
- docs/docs/tutorial-basics/create-a-page.md
- docs/docs/tutorial-extras/category.json
- docs/package.json
- docs/src/components/HomepageFeatures/styles.module.css
- docs/src/css/custom.css
- docs/src/pages/index.module.css
- docs/tsconfig.json
Additional context used
LanguageTool
docs/src/pages/markdown-page.md
[grammar] ~7-~7: Did you mean “to React”?
Context: ...# Markdown page example You don't need React to write simple standalone pages.(NEEDNT_TO_DO_AND_DONT_NEED_DO)
docs/docs/tutorial-basics/deploy-your-site.md
[style] ~31-~31: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...most anywhere** easily, for free or very small cost (read the **[Deployment Guide](htt...(EN_WEAK_ADJECTIVE)
docs/docs/tutorial-basics/congratulations.md
[style] ~7-~7: Consider rephrasing this to strengthen your wording.
Context: ...earned the basics of Docusaurus and made some changes to the initial template. Docusauru...(MAKE_CHANGES)
[style] ~13-~13: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 654 characters long)
Context: ...gy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus...(EN_EXCESSIVE_EXCLAMATION)
docs/docs/tutorial-extras/manage-docs-versions.md
[duplication] ~54-~54: Possible typo: you repeated a word
Context: ...-versioned_docs/version-1.0/hello.mdupdateshttp://localhost:3000/docs/hello-docs/hello.mdupdateshttp://localhost:3000/docs/next/hello...(ENGLISH_WORD_REPEAT_RULE)
docs/docs/intro.md
[uncategorized] ~32-~32: You might be missing the article “the” here.
Context: ... editor. The command also installs all necessary dependencies you need to run Docusaurus...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[style] ~43-~43: Consider a shorter alternative to avoid wordiness.
Context: ...nges the directory you're working with. In order to work with your newly created Docusaurus...(IN_ORDER_TO_PREMIUM)
docs/docs/tutorial-basics/markdown-features.mdx
[style] ~98-~98: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...erous ::: ``` :::tip My tip Use this awesome feature option ::: :::danger Take car...(AWESOME)
Markdownlint
docs/README.md
5-5: Expected: h2; Actual: h3
Heading levels should only increment by one level at a time(MD001, heading-increment)
8-8: null
Dollar signs used before commands without showing output(MD014, commands-show-output)
14-14: null
Dollar signs used before commands without showing output(MD014, commands-show-output)
22-22: null
Dollar signs used before commands without showing output(MD014, commands-show-output)
32-32: null
Dollar signs used before commands without showing output(MD014, commands-show-output)
38-38: null
Dollar signs used before commands without showing output(MD014, commands-show-output)
7-7: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
13-13: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
21-21: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
31-31: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
37-37: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
docs/docs/intro.md
45-45: null
Bare URL used(MD034, no-bare-urls)
GitHub Check: test
docs/src/components/HomepageFeatures/index.tsx
[failure] 14-14:
Require statement not part of import statement
[failure] 24-24:
Require statement not part of import statement
[failure] 35-35:
Require statement not part of import statement
Additional comments not posted (14)
docs/src/pages/markdown-page.md (1)
1-7: Markdown Content is CorrectThe content of the Markdown file is correctly formatted and appropriate for an introductory page. The grammar suggestion from LanguageTool is a false positive and should be ignored.
Tools
LanguageTool
[grammar] ~7-~7: Did you mean “to React”?
Context: ...# Markdown page example You don't need React to write simple standalone pages.(NEEDNT_TO_DO_AND_DONT_NEED_DO)
docs/sidebars.ts (1)
1-31: Sidebar Configuration is Correct and Well-DocumentedThe sidebar configuration for the Docusaurus site is correctly implemented and well-documented. The comments provide clear guidance on how to use and modify the sidebar, which is beneficial for future maintenance and updates.
docs/README.md (2)
8-8: Use of dollar signs before commands is appropriate.The use of dollar signs before commands is a common practice in documentation to indicate shell commands and does not require changes.
Also applies to: 14-14, 22-22, 32-32, 38-38
Tools
Markdownlint
8-8: null
Dollar signs used before commands without showing output(MD014, commands-show-output)
27-41: Deployment instructions are clear and comprehensive.The provided deployment instructions are well-detailed and cater to different user scenarios (using SSH and not using SSH).
Tools
Markdownlint
32-32: null
Dollar signs used before commands without showing output(MD014, commands-show-output)
38-38: null
Dollar signs used before commands without showing output(MD014, commands-show-output)
31-31: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
37-37: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
docs/src/pages/index.tsx (3)
1-8: Imports are appropriate and correctly used.All imports are standard for a Docusaurus site and are correctly utilized within the file.
10-29: Well-implemented Homepage Header.The
HomepageHeaderfunction correctly utilizesuseDocusaurusContextto access site configuration and returns a well-structured JSX element for the homepage header.
32-44: Home Function is correctly implemented.The
Homefunction effectively usesuseDocusaurusContextand correctly structures the main layout of the homepage using various components.docs/docs/intro.md (1)
1-47: Content is well-structured and informative.The markdown file is well-organized, providing clear instructions and useful links. It serves as an effective introduction to Docusaurus.
Tools
LanguageTool
[uncategorized] ~32-~32: You might be missing the article “the” here.
Context: ... editor. The command also installs all necessary dependencies you need to run Docusaurus...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[style] ~43-~43: Consider a shorter alternative to avoid wordiness.
Context: ...nges the directory you're working with. In order to work with your newly created Docusaurus...(IN_ORDER_TO_PREMIUM)
Markdownlint
45-45: null
Bare URL used(MD034, no-bare-urls)
docs/docs/tutorial-extras/translate-your-site.md (1)
1-88: Content is well-structured and informative.The markdown file is well-organized, providing clear instructions and useful tips for translating and configuring the site for multiple locales. It serves as an effective guide for site internationalization.
docs/src/components/HomepageFeatures/index.tsx (1)
47-73: Components implemented correctly.The
FeatureandHomepageFeaturescomponents are implemented correctly using React best practices. The use ofclsxfor conditional classes and modular CSS viastylesis appropriate. The mapping ofFeatureListwithkeyset to index is acceptable given the static nature of the list.docs/docusaurus.config.ts (1)
5-98: Configuration settings are comprehensive and correctly implemented.The Docusaurus configuration settings are comprehensive, covering essential aspects like site metadata, deployment settings, broken link handling, internationalization, and theming. The use of TypeScript for type safety and the
satisfieskeyword to ensure type conformity is commendable.docs/docs/tutorial-basics/create-a-blog-post.md (1)
1-6: Metadata and Title Review: ApprovedThe metadata and title are correctly formatted and appropriate for the content.
docs/docs/tutorial-basics/congratulations.md (2)
1-6: Metadata and Title Review: ApprovedThe metadata and title are correctly formatted and appropriate for the content.
7-23: Content Review: ApprovedThe content is engaging and provides useful links for further exploration. The use of exclamation marks is appropriate for the context and does not need adjustment.
Tools
LanguageTool
[style] ~7-~7: Consider rephrasing this to strengthen your wording.
Context: ...earned the basics of Docusaurus and made some changes to the initial template. Docusauru...(MAKE_CHANGES)
[style] ~13-~13: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 654 characters long)
Context: ...gy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus...(EN_EXCESSIVE_EXCLAMATION)
| --- | ||
| sidebar_position: 5 | ||
| --- | ||
|
|
||
| # Deploy your site | ||
|
|
||
| Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**). | ||
|
|
||
| It builds your site as simple **static HTML, JavaScript and CSS files**. | ||
|
|
||
| ## Build your site | ||
|
|
||
| Build your site **for production**: | ||
|
|
||
| ```bash | ||
| npm run build | ||
| ``` | ||
|
|
||
| The static files are generated in the `build` folder. | ||
|
|
||
| ## Deploy your site | ||
|
|
||
| Test your production build locally: | ||
|
|
||
| ```bash | ||
| npm run serve | ||
| ``` | ||
|
|
||
| The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/). | ||
|
|
||
| You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**). |
There was a problem hiding this comment.
Documentation Content is Well-Written
The instructions for deploying a site using Docusaurus are clear and well-structured. Consider replacing "very small cost" with "minimal cost" to strengthen the statement.
- You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).
+ You can now deploy the `build` folder **almost anywhere** easily, **for free** or at minimal cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| sidebar_position: 5 | |
| --- | |
| # Deploy your site | |
| Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**). | |
| It builds your site as simple **static HTML, JavaScript and CSS files**. | |
| ## Build your site | |
| Build your site **for production**: | |
| ```bash | |
| npm run build | |
| ``` | |
| The static files are generated in the `build` folder. | |
| ## Deploy your site | |
| Test your production build locally: | |
| ```bash | |
| npm run serve | |
| ``` | |
| The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/). | |
| You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**). | |
| --- | |
| sidebar_position: 5 | |
| --- | |
| # Deploy your site | |
| Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**). | |
| It builds your site as simple **static HTML, JavaScript and CSS files**. | |
| ## Build your site | |
| Build your site **for production**: | |
| ```bash | |
| npm run build | |
| ``` | |
| The static files are generated in the `build` folder. | |
| ## Deploy your site | |
| Test your production build locally: | |
| ```bash | |
| npm run serve | |
| ``` | |
| The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/). | |
| You can now deploy the `build` folder **almost anywhere** easily, **for free** or at minimal cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**). |
Tools
LanguageTool
[style] ~31-~31: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...most anywhere** easily, for free or very small cost (read the **[Deployment Guide](htt...(EN_WEAK_ADJECTIVE)
|
|
||
| ### Installation | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Specify language for code blocks.
For better readability and syntax highlighting, specify the language for all fenced code blocks.
Suggested fix for all relevant lines:
-```
+```shAlso applies to: 13-13, 21-21, 31-31, 37-37
Tools
Markdownlint
7-7: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
|
|
||
| This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. | ||
|
|
||
| ### Installation |
There was a problem hiding this comment.
Adjust heading level for better structure.
The heading at line 5 should be an h2 (##) instead of h3 (###) to maintain a proper incremental heading level.
Suggested fix:
-### Installation
+## InstallationCommittable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Installation | |
| ## Installation |
Tools
Markdownlint
5-5: Expected: h2; Actual: h3
Heading levels should only increment by one level at a time(MD001, heading-increment)
| --- | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # Manage Docs Versions | ||
|
|
||
| Docusaurus can manage multiple versions of your docs. | ||
|
|
||
| ## Create a docs version | ||
|
|
||
| Release a version 1.0 of your project: | ||
|
|
||
| ```bash | ||
| npm run docusaurus docs:version 1.0 | ||
| ``` | ||
|
|
||
| The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created. | ||
|
|
||
| Your docs now have 2 versions: | ||
|
|
||
| - `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs | ||
| - `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs** | ||
|
|
||
| ## Add a Version Dropdown | ||
|
|
||
| To navigate seamlessly across versions, add a version dropdown. | ||
|
|
||
| Modify the `docusaurus.config.js` file: | ||
|
|
||
| ```js title="docusaurus.config.js" | ||
| export default { | ||
| themeConfig: { | ||
| navbar: { | ||
| items: [ | ||
| // highlight-start | ||
| { | ||
| type: 'docsVersionDropdown', | ||
| }, | ||
| // highlight-end | ||
| ], | ||
| }, | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| The docs version dropdown appears in your navbar: | ||
|
|
||
|  | ||
|
|
||
| ## Update an existing version | ||
|
|
||
| It is possible to edit versioned docs in their respective folder: | ||
|
|
||
| - `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello` | ||
| - `docs/hello.md` updates `http://localhost:3000/docs/next/hello` |
There was a problem hiding this comment.
Comprehensive guide on managing documentation versions
This document is well-structured and provides clear, step-by-step instructions on managing documentation versions in Docusaurus. The use of JavaScript snippets and an image enhances understanding.
There is a minor issue with duplication in the text around lines 54-55. Consider rephrasing to avoid redundancy.
Tools
LanguageTool
[duplication] ~54-~54: Possible typo: you repeated a word
Context: ...-versioned_docs/version-1.0/hello.mdupdateshttp://localhost:3000/docs/hello-docs/hello.mdupdateshttp://localhost:3000/docs/next/hello...(ENGLISH_WORD_REPEAT_RULE)
|
|
||
| You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. | ||
|
|
||
| The command also installs all necessary dependencies you need to run Docusaurus. |
There was a problem hiding this comment.
Grammar Correction Needed.
Consider adding "the" before "Docusaurus" to improve readability.
- The command also installs all necessary dependencies you need to run Docusaurus.
+ The command also installs all necessary dependencies you need to run the Docusaurus.Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The command also installs all necessary dependencies you need to run Docusaurus. | |
| The command also installs all necessary dependencies you need to run the Docusaurus. |
Tools
LanguageTool
[uncategorized] ~32-~32: You might be missing the article “the” here.
Context: ... editor. The command also installs all necessary dependencies you need to run Docusaurus...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
| npm run start | ||
| ``` | ||
|
|
||
| The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. |
There was a problem hiding this comment.
Simplify Language.
Consider simplifying the phrase "In order to" to avoid wordiness.
- In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
+ To work with your newly created Docusaurus site, navigate the terminal there.Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. | |
| The `cd` command changes the directory you're working with. To work with your newly created Docusaurus site, navigate the terminal there. |
Tools
LanguageTool
[style] ~43-~43: Consider a shorter alternative to avoid wordiness.
Context: ...nges the directory you're working with. In order to work with your newly created Docusaurus...(IN_ORDER_TO_PREMIUM)
|
|
||
| The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. | ||
|
|
||
| The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. |
There was a problem hiding this comment.
Avoid Bare URLs.
Consider using markdown syntax to make the URL clickable.
- ready for you to view at http://localhost:3000/.
+ ready for you to view at [http://localhost:3000/](http://localhost:3000/).Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. | |
| The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at [http://localhost:3000/](http://localhost:3000/). |
Tools
Markdownlint
45-45: null
Bare URL used(MD034, no-bare-urls)
| type FeatureItem = { | ||
| title: string; | ||
| Svg: React.ComponentType<React.ComponentProps<"svg">>; | ||
| description: JSX.Element; | ||
| }; | ||
|
|
||
| const FeatureList: FeatureItem[] = [ | ||
| { | ||
| title: "All you need is TypeScript", | ||
| Svg: require("@site/static/img/undraw_docusaurus_mountain.svg").default, | ||
| description: ( | ||
| <> | ||
| typed-api-spec's API definition schema is built on top of TypeScript, so | ||
| you can use the full power of the type system | ||
| </> | ||
| ), | ||
| }, | ||
| { | ||
| title: "type-safe, zero-runtime client", | ||
| Svg: require("@site/static/img/undraw_docusaurus_tree.svg").default, | ||
| description: ( | ||
| <> | ||
| typed-api-spec provides type-safe, 0kb bundle size API client. You can | ||
| use it with zero-runtime, zero-overhead, zero-dependency and | ||
| zero-learning-cost (because it is just <i>fetch</i>!). | ||
| </> | ||
| ), | ||
| }, | ||
| { | ||
| title: "Framework-agnostic", | ||
| Svg: require("@site/static/img/undraw_docusaurus_react.svg").default, | ||
| description: ( | ||
| <> | ||
| typed-api-spec does not require any other dependencies. It supports | ||
| server frameworks(e.g. Express, Fastify) and validation libraries)(e.g. | ||
| zod, valibot), but these are optional and you can use only those you | ||
| need. | ||
| </> | ||
| ), | ||
| }, |
There was a problem hiding this comment.
Replace require with import for SVGs.
The use of require for importing SVGs is flagged by static analysis tools. It's recommended to use ES6 imports for better bundling and tree-shaking support. Here's how you can refactor it:
- Svg: require("@site/static/img/undraw_docusaurus_mountain.svg").default,
+ import MountainSvg from "@site/static/img/undraw_docusaurus_mountain.svg";
+ Svg: MountainSvg,Apply similar changes for other SVG imports in this file.
Committable suggestion was skipped due to low confidence.
Tools
GitHub Check: test
[failure] 14-14:
Require statement not part of import statement
[failure] 24-24:
Require statement not part of import statement
[failure] 35-35:
Require statement not part of import statement
There was a problem hiding this comment.
Actionable comments posted: 0
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (1)
- docs/src/components/HomepageFeatures/index.tsx (1 hunks)
Files skipped from review as they are similar to previous changes (1)
- docs/src/components/HomepageFeatures/index.tsx
There was a problem hiding this comment.
Actionable comments posted: 2
Outside diff range, codebase verification and nitpick comments (1)
docs/docs/tutorial-basics/markdown-features.mdx (1)
98-98: Consider revising the word 'awesome'.The use of the word "awesome" may be seen as too informal for some professional documentation contexts.
Consider using a more formal alternative to maintain a professional tone throughout the documentation.
- Use this awesome feature option + Use this excellent feature optionTools
LanguageTool
[style] ~98-~98: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...erous ::: ``` :::tip My tip Use this awesome feature option ::: :::danger Take car...(AWESOME)
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (10)
- .github/workflows/doc.yaml (1 hunks)
- .prettierignore (1 hunks)
- docs/babel.config.js (1 hunks)
- docs/docs/tutorial-basics/create-a-document.md (1 hunks)
- docs/docs/tutorial-basics/create-a-page.md (1 hunks)
- docs/docs/tutorial-basics/markdown-features.mdx (1 hunks)
- docs/docs/tutorial-extras/manage-docs-versions.md (1 hunks)
- docs/docs/tutorial-extras/translate-your-site.md (1 hunks)
- docs/sidebars.ts (1 hunks)
- docs/src/css/custom.css (1 hunks)
Files skipped from review due to trivial changes (2)
- docs/docs/tutorial-basics/create-a-document.md
- docs/docs/tutorial-basics/create-a-page.md
Files skipped from review as they are similar to previous changes (4)
- .github/workflows/doc.yaml
- docs/babel.config.js
- docs/docs/tutorial-extras/translate-your-site.md
- docs/src/css/custom.css
Additional context used
GitHub Check: test
docs/sidebars.ts
[failure] 1-1:
Cannot find module '@docusaurus/plugin-content-docs' or its corresponding type declarations.
LanguageTool
docs/docs/tutorial-extras/manage-docs-versions.md
[duplication] ~54-~54: Possible typo: you repeated a word
Context: ...-versioned_docs/version-1.0/hello.mdupdateshttp://localhost:3000/docs/hello-docs/hello.mdupdateshttp://localhost:3000/docs/next/hello...(ENGLISH_WORD_REPEAT_RULE)
docs/docs/tutorial-basics/markdown-features.mdx
[style] ~98-~98: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...erous ::: ``` :::tip My tip Use this awesome feature option ::: :::danger Take car...(AWESOME)
Additional comments not posted (8)
docs/sidebars.ts (1)
3-31: Approve sidebar configuration.The sidebar configuration is well-structured and follows best practices for Docusaurus. It includes both autogenerated and manually defined sidebars, which provides flexibility in documentation structure.
docs/docs/tutorial-basics/markdown-features.mdx (7)
7-8: Clear and concise introduction to Markdown features.The introduction effectively sets the context for the document by linking to the Markdown syntax and highlighting additional features supported by Docusaurus.
11-26: Well-documented Front Matter example.The example provided for Front Matter is clear and well-documented, using a practical example that includes essential metadata fields. This section effectively educates users on how to use Front Matter in their Markdown files.
30-40: Accurate demonstration of link usage in Markdown.This section correctly demonstrates how to use both absolute and relative links in Markdown, which is crucial for documentation that might be hosted at various paths.
44-60: Detailed explanation and examples of image embedding.The instructions and examples for embedding images using both absolute and relative paths are clear and helpful. This section will assist users in effectively managing images in their documentation.
62-76: Code blocks and syntax highlighting showcased effectively.The examples of JSX code blocks with syntax highlighting are correctly formatted and demonstrate the capability of Docusaurus to handle complex Markdown features.
80-106: Effective use of admonitions to highlight important information.The section on admonitions uses Docusaurus's special syntax to create visually distinct callouts, which are essential for drawing attention to important pieces of information in documentation.
Tools
LanguageTool
[style] ~98-~98: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...erous ::: ``` :::tip My tip Use this awesome feature option ::: :::danger Take car...(AWESOME)
110-153: Innovative use of MDX for interactive documentation.The use of MDX to integrate React components directly into the Markdown is innovative and enhances the interactivity of the documentation. This section effectively demonstrates how to create and use custom React components within the documentation.
| @@ -0,0 +1,31 @@ | |||
| import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"; | |||
There was a problem hiding this comment.
Resolve module import issue.
The import of @docusaurus/plugin-content-docs is flagged by static analysis as missing. Ensure that the module is installed or the path is correctly configured in tsconfig.json.
Tools
GitHub Check: test
[failure] 1-1:
Cannot find module '@docusaurus/plugin-content-docs' or its corresponding type declarations.
| --- | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # Manage Docs Versions | ||
|
|
||
| Docusaurus can manage multiple versions of your docs. | ||
|
|
||
| ## Create a docs version | ||
|
|
||
| Release a version 1.0 of your project: | ||
|
|
||
| ```bash | ||
| npm run docusaurus docs:version 1.0 | ||
| ``` | ||
|
|
||
| The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created. | ||
|
|
||
| Your docs now have 2 versions: | ||
|
|
||
| - `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs | ||
| - `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs** | ||
|
|
||
| ## Add a Version Dropdown | ||
|
|
||
| To navigate seamlessly across versions, add a version dropdown. | ||
|
|
||
| Modify the `docusaurus.config.js` file: | ||
|
|
||
| ```js title="docusaurus.config.js" | ||
| export default { | ||
| themeConfig: { | ||
| navbar: { | ||
| items: [ | ||
| // highlight-start | ||
| { | ||
| type: "docsVersionDropdown", | ||
| }, | ||
| // highlight-end | ||
| ], | ||
| }, | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| The docs version dropdown appears in your navbar: | ||
|
|
||
|  | ||
|
|
||
| ## Update an existing version | ||
|
|
||
| It is possible to edit versioned docs in their respective folder: | ||
|
|
||
| - `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello` | ||
| - `docs/hello.md` updates `http://localhost:3000/docs/next/hello` |
There was a problem hiding this comment.
Approve tutorial content and address duplication.
The tutorial on managing documentation versions is clear and informative. However, the duplication issue mentioned in previous comments around lines 54-55 still needs addressing to avoid redundancy.
Consider rephrasing the duplicated text to enhance clarity and avoid redundancy.
Tools
LanguageTool
[duplication] ~54-~54: Possible typo: you repeated a word
Context: ...-versioned_docs/version-1.0/hello.mdupdateshttp://localhost:3000/docs/hello-docs/hello.mdupdateshttp://localhost:3000/docs/next/hello...(ENGLISH_WORD_REPEAT_RULE)
Summary by CodeRabbit
New Features
typed-api-speclibrary.Bug Fixes
.gitignorefile, preventing unnecessary files from being tracked.Documentation
README.mdfile detailing installation, local development, build processes, and deployment instructions.Style
Chores