swagle commented on code in PR #54: URL: https://github.com/apache/ozone-site/pull/54#discussion_r1456832851
########## CONTRIBUTING.md: ########## @@ -0,0 +1,244 @@ +# Apache Ozone Website Contribution Guide + +Ozone is an Apache project. The bug tracking system for Ozone and its website is under the [Apache Jira project named HDDS](https://issues.apache.org/jira/projects/HDDS/). + +This document summarize the contribution process. + +## What Can I Contribute? + +- **Issues**: If you find an issue or have an idea for an improvement to the website, please [file a Jira issue](#filing-jira-issues). Even if you are not able to fix the issue, please report it so we can find someone who can. + +- **Documentation**: You can fix anything from a minor typo, an unclear or outdated section, or a completely missing page. Most changes in this area can be done with just basic markdown knowledge. + +- **Theme and Styling**: You can help improve the overall appearance of the Ozone website using standard web development tools like Javascript, React, HTML, and CSS. You can also create or modify graphics and images used on the site. + +- **Tests**: HDDS-9601 will implement a basic set of tests to run as part of CI for the website, but you can help expand or improve them. + +- **Tools**: You can submit improvements to how we use various tools like pnpm, docker, and Dependabot that are used in the development of the website. + +## Filing Jira Issues + +Please follow the same [Jira guidelines](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md#jira-guideline) as the main Ozone project when filing improvements or issues for the website. Website Jira issues are also under the HDDS project, but can be tagged with `website` and `documentation` to distinguish them from changes to Ozone itself. + +## Modifying the Website + +The Apache Ozone Website uses [Docusaurus](https://docusaurus.io/) as a static site generator. Most simple updates to the website can be done with little knowledge of Docusaurus, but for more complex modifications to the website or a better understanding of how it is built, see the Docusaurus [documentation](https://docusaurus.io/docs) and [API](https://docusaurus.io/docs/cli). + +### Directory Layout + +- [docusaurus.config.js](https://docusaurus.io/docs/configuration) + - The main configuration file for the docusaurus site. + +- [docs](https://docusaurus.io/docs/docs-introduction) + - Documentation pages. + - The layout of subdirectories determines the layout of the sidebar in the docs section. + +- [versioned_docs](https://docusaurus.io/docs/versioning) + - Contains older versions of the documentation. + - Only update files in this directory if you need to backport a fix to older versions of the documentation. + +- [sidebars.js](https://docusaurus.io/docs/sidebar/autogenerated) + - Configuration of the documentation menu sidebars. + - This file should not need to be modified since the menu will be auto-generated from the directory and file layout. + +- [versioned_sidebars](https://docusaurus.io/docs/versioning) + - Contains older versions of the documentation sidebars. + - Only update files in this directory if you need to backport a fix to older versions of the documentation. + +- [versions.json](https://docusaurus.io/docs/versioning) + - Contains a list of all versions of the documentation. + +- [static](https://docusaurus.io/docs/static-assets) + - Contains non-code files that are directly copied to the build output, including images. + +- **src** + - [css](https://docusaurus.io/docs/styling-layout) + - Global CSS files loaded by `docusaurus.config.js` + + - [pages](https://docusaurus.io/docs/static-assets) + - Static pages outside of the documentation section. + + - **index.js** + - The website homepage. + + - [theme](https://docusaurus.io/docs/swizzling) + - Contains theme overrides of Docusaurus specific components created with [swizzling](https://docusaurus.io/docs/swizzling). + - Styling of the components is done with [CSS Modules](https://docusaurus.io/docs/styling-layout#css-modules) which are stored in the directory with their component. + +### Creating or Updating Documentation + +#### Page Format + +Docusaurus docs are written in markdown. All standard markdown formatting can be used, but docusaurus provides some additional features to enhance your pages. Complete details are documented in [Docusaurus markdown features](https://docusaurus.io/docs/markdown-features), but a high level summary is provided here: + +- The [.mdx file format](https://docusaurus.io/docs/markdown-features/react) allows you to embed Javascript React components into your markdown for interactive features. + +- [Tabs](https://docusaurus.io/docs/markdown-features/tabs) can show multiple possibilities succinctly. + +- Standard Markdown [Code blocks](https://docusaurus.io/docs/markdown-features/code-blocks) have extra features, including: + - [Titles](https://docusaurus.io/docs/markdown-features/code-blocks#code-title) + - [Optional line numbers](https://docusaurus.io/docs/markdown-features/code-blocks#line-numbering) + - [Multi-language tabs](https://docusaurus.io/docs/markdown-features/code-blocks#multi-language-support-code-blocks) + + +- [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) (note, tip, info. warning, danger) optionally with [custom titles](https://docusaurus.io/docs/markdown-features/admonitions#specifying-title). + +- Link to specific headings in pages with [Heading IDs](https://docusaurus.io/docs/markdown-features/toc#heading-ids) + +- Various strategies for adding [graphics to markdown pages](https://docusaurus.io/docs/markdown-features/assets) + +- Inline diagrams with [Mermaid](https://docusaurus.io/docs/markdown-features/diagrams) + +#### Best Practices + +Docusaurus provides many options for laying out documentation pages and their metadata. The following best practices are followed by this repo, and some may be enforced by CI checks once HDDS-9601 is complete. + +- [Number prefixes](https://docusaurus.io/docs/sidebar/autogenerated#using-number-prefixes) should be used for all file and sdiebar directory names to enforce their order in the website and local editors. + - Number prefixes will be automatically removed from links in the Docusaurus build. + +- [Category links](https://docusaurus.io/docs/sidebar/items#category-link) should not be used. They make it easy to miss pages when looking at the sidebar since it is unclear if they are just a dropdown or also contain documentation. + +- Let Docusaurus automatically generate a webpage URL from the file name. + +- File names and therefore generated URLs should all be `kebab-case`. + +- Let Docusaurus automatically generate the page's title from its top level markdown heading instead of using `title` in the frontmatter. This is different from the sidebar label or URL slug. + +- Use relative file paths for all links between pages. + - This keeps page links pointing to the current version of the documentation. + - See [Markdown Links](https://docusaurus.io/docs/markdown-features/links) in Docusaurus for more information. + +- Use short, succinct labels in the sidebar. + - For example, the pages on bucket layouts may be organized as: + ``` + ... + Buckets + ... + Layouts + File System Optimized (FSO) + Object Store (OBS) + ``` + + - This avoids a verbose sidebar with duplicate information like this example: Review Comment: Nice suggestion - this is important to keep it from becoming fugly :-) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
