Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework | Kserve Documentation #347

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

Syntax-Error-1337
Copy link

@Syntax-Error-1337 Syntax-Error-1337 commented Feb 29, 2024

I will remake all section. currently added 2 section

Proposed Changes

I am reworking on documentation website.
Using: Docusaurus
Light Theme:
image

Dark Theme:
image

Light Theme:
image

Dark Theme :
image

Docusaurus vs MkDocs: Key Differences
Docusaurus and MkDocs are popular documentation site generators that help create and maintain websites. While they serve a similar purpose, there are key differences between the two:

Customization: Docusaurus offers a more opinionated approach with a pre-built design system, allowing for easy customization through themes and plugins. On the other hand, MkDocs provides a simpler and more flexible templating system, giving users more control over the site's appearance.

Plugin Ecosystem: Docusaurus has a wider range of plugins available to extend functionality, including features like internationalization and analytics integration. MkDocs, while not as extensive, still offers several useful plugins but may require more manual configuration for advanced features.

Documentation Structure: Docusaurus is built to handle large documentation sites with multiple sections and versions, making it ideal for projects with complex documentation needs. MkDocs, on the other hand, is better suited for smaller projects with a simpler structure, where a single documentation file may be sufficient.

Built-in Search: Docusaurus includes a powerful built-in search functionality that indexes the site's content, allowing users to easily search and find specific information. MkDocs, while offering search through third-party plugins, lacks the built-in search capability and may require additional configuration for advanced search features.

Community and Support: Docusaurus has a larger community and a more active development team, providing faster updates and timely support. MkDocs also has an active community but may have slightly slower updates and responses to issues.

Integration with external tools: Docusaurus is developed and maintained by Facebook, which means it integrates seamlessly with other Facebook-developed tools and workflows. MkDocs, being an open-source project, can be integrated with various external tools and services through plugins but may require more configuration and setup.

In summary, Docusaurus offers more pre-built customization options and extensive plugins, making it suitable for large and complex documentation sites. MkDocs provides a simpler and more flexible templating system, ideal for smaller projects with simpler documentation needs.

Copy link

oss-prow-bot bot commented Feb 29, 2024

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: Syntax-Error-1337
Once this PR has been reviewed and has the lgtm label, please assign theofpa for approval by writing /assign @theofpa in a comment. For more information see:The Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Copy link

netlify bot commented Feb 29, 2024

Deploy Preview for elastic-nobel-0aef7a ready!

Name Link
🔨 Latest commit 94a9d51
🔍 Latest deploy log https://app.netlify.com/sites/elastic-nobel-0aef7a/deploys/660bb314753dd10008fb1156
😎 Deploy Preview https://deploy-preview-347--elastic-nobel-0aef7a.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@yuzisun
Copy link
Member

yuzisun commented Mar 24, 2024

@Syntax-Error-1337 Thanks for working on this! let discuss the plan if we want to switch

@Syntax-Error-1337
Copy link
Author

Hello @yuzisun, I've been looking forward to your feedback to determine whether you find the proposed rework advantageous. Upon your approval, I'm ready to move forward with the rebuilding process.

This rebuilding can be beneficial in long term.

Switching from Mkdocs to Docusaurus for documentation purposes can offer several benefits, largely because Docusaurus has a set of features specifically designed to enhance the user experience and the manageability of documentation

  1. Built-In Search Functionality
    Docusaurus comes with Algolia DocSearch integration out-of-the-box, providing a powerful, fast, and accurate search experience for your documentation without the need for extensive configuration.
  2. Versioning Support
    Docusaurus supports versioning natively, making it easy to maintain documentation for multiple versions of your product or library simultaneously. This is especially useful for projects that evolve over time.
  3. Internationalization (i18n)
    Docusaurus has built-in support for internationalization, allowing you to create and manage documentation in multiple languages easily.
  4. Markdown Extensions and Customization
    While both MkDocs and Docusaurus support Markdown for documentation, Docusaurus allows for extensive customization and extension of Markdown, including the addition of React components directly within your Markdown files.
  5. Theme and Appearance Customization
    Docusaurus offers more extensive theming and customization options compared to MkDocs. You can customize the look and feel of your site with CSS variables and even use React to create custom layouts.
  6. Dynamic Content Support
    With Docusaurus, you can embed dynamic content such as React components within your documentation. This is particularly useful for interactive examples or demos.
  7. Blog Support
    Docusaurus includes integrated blog support, allowing you to maintain a blog alongside your documentation. This feature is built-in and requires minimal setup.
  8. Community and Ecosystem
    Docusaurus is backed by Facebook and has a large and active community. This results in a wide range of plugins and integrations that can enhance your documentation site.
  9. Performance Optimizations
    Docusaurus sites are optimized for performance, with features like code splitting and lazy loading out of the box, ensuring your documentation loads quickly.
  10. SEO Optimization
    Docusaurus provides better out-of-the-box support for SEO optimizations, ensuring that your documentation is more visible to search engines.

@spolti
Copy link

spolti commented Apr 2, 2024

Antora is a good option as well, but it is ascii doctor based.

@Syntax-Error-1337
Copy link
Author

@spolti yes even Antora is a good option.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants