search

kserve / website

User documentation for KServe.
https://kserve.github.io/website/
Apache License 2.0
103 stars 109 forks source link

Rework | Kserve Documentation #347

Open Syntax-Error-1337 opened 4 months ago

Syntax-Error-1337 commented 4 months ago

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.

-

oss-prow-bot[bot] commented 4 months ago

[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: - **[OWNERS](https://github.com/kserve/website/blob/main/OWNERS)** Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment
netlify[bot] commented 4 months ago

Deploy Preview for elastic-nobel-0aef7a ready!

Name Link
Latest commit 94a9d51e3efff3e6288298fb1bacd05b6accbeb2
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 commented 3 months ago

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

Syntax-Error-1337 commented 3 months ago

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 commented 3 months ago

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

Syntax-Error-1337 commented 3 months ago

@spolti yes even Antora is a good option.