-
Notifications
You must be signed in to change notification settings - Fork 33
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
- Loading branch information
Showing
2 changed files
with
248 additions
and
71 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,243 @@ | ||
| # Apache Ozone Website Contribution Guide | ||
|
|
||
| The Apache Ozone is a top-level Apache project and is licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). 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 summarizes 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](https://issues.apache.org/jira/browse/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: | ||
| ``` | ||
| ... | ||
| Buckets | ||
| ... | ||
| Bucket Layouts | ||
| File System Optimized Bucket Layout | ||
| Object Store Bucket Layout | ||
| ``` | ||
|
|
||
| - Sidebar labels are automatically generated from page titles. To use a different sidebar label, use the `sidebar_label` property in the page's frontmatter. | ||
|
|
||
| - Don't rely on Ozone specific acronyms in the sidebar. This makes docs navigation more beginner friendly. | ||
| - For example, the pages on bucket layouts may be organized as: | ||
| ``` | ||
| ... | ||
| Buckets | ||
| ... | ||
| Layouts | ||
| File System Optimized (FSO) | ||
| Object Store (OBS) | ||
| ``` | ||
|
|
||
| - Which is easier for a new Ozone user to follow than this: | ||
| ``` | ||
| ... | ||
| Buckets | ||
| ... | ||
| Layouts | ||
| FSO | ||
| OBS | ||
| ``` | ||
| - Use descriptive page titles. | ||
| - Pages may be linked directly from other sources and users should be able to tell what the page is without looking at the sidebar. | ||
| - There may also be multiple pages about the same topic, for example Kerberos. Readers should be able to tell which aspect of Kerberos the page is about to distinguish it from other pages. | ||
| - For example, pages in the security configuration section may be organized like this: | ||
| ``` | ||
| Configuration | ||
| ... | ||
| Security | ||
| ... | ||
| Kerberos | ||
| ``` | ||
| - The sidebar label makes sense because it has the context of the parent sidebar sections, however the Kerberos page should have a title like "Configuring Kerberos" instead of just "Kerberos" like its sidebar label. | ||
| ### Updating Graphics | ||
| When adding or updating graphics in the Ozone website, please follow these guidelines: | ||
| - Use SVG files for flat icons with minimal colors. These scale better and are smaller in size. | ||
| - Use PNG files for images that have more colors or complexity. | ||
| - Graphics used with documentation should go in the `docs` directory (not the `static` directory) so that they can be versioned with the rest of the documentation. | ||
| ### Updating Theme or Styling | ||
| Changing appearance or theme of the website from Docusaurus defaults can be done with React and CSS. See the Docusaurus documentation on [Styling and Layout](https://docusaurus.io/docs/styling-layout) and [Swizzling](https://docusaurus.io/docs/swizzling) for more information. Here are some general guidelines: | ||
| - To update the website homepage, modify `src/pages/index.js` and add or modify CSS files as needed. | ||
| - For global CSS configurations: | ||
| 1. Create or modify a file in `src/css`. | ||
| 2. If creating a new file, add it to `config.presets.theme.customCss` in `docusaurus.config.js` to be loaded. | ||
| - For component specific CSS configurations, add a [CSS module](https://docusaurus.io/docs/styling-layout#css-modules) to the `theme` subdirectory of the component being modified. | ||
| - Make sure styling changes work in both [light and dark modes](https://docusaurus.io/docs/styling-layout#dark-mode). | ||
| ### Previewing Your Modifications Locally | ||
| Docusaurus supports previewing the website locally. Below are various options to launch a preview of the site at `localhost:3000` on your machine. | ||
| **NOTE** If using the [Docusaurus development server](https://docusaurus.io/docs/installation#running-the-development-server), changes to `docusaurus.config.js` may not be automatically reloaded and require the server to be restarted. | ||
| #### Option 1: Docker (Recommended) | ||
| The project includes a `Dockerfile` and a `compose.yml` file to build and run the website in a containerized environment. This creates a docker image called `ozone-site-dev` with all the dependencies included, and uses it to run the [Docusaurus development server](https://docusaurus.io/docs/installation#running-the-development-server). | ||
| 1. Install [docker](https://docs.docker.com/engine/install/). | ||
| 2. Install [docker compose](https://docs.docker.com/compose/install/). | ||
| 3. Run `docker compose up` from the repository root. | ||
| 4. Preview the website at `localhost:3000` in your browser. | ||
| - Any changes made in the repository will be reflected in the preview. | ||
| 5. Press `Ctrl+C` or run `docker compose down` to stop the preview. | ||
| #### Option 2: pnpm | ||
| Build and run the website locally with the `pnpm` package manager. | ||
| 1. Install [pnpm](https://pnpm.io/installation), which will be used to build the site. | ||
| 2. Install dependencies required to build the website by running `pnpm install` at the website root. | ||
| - [**Development Server**](https://docusaurus.io/docs/installation#running-the-development-server): This option will start the Docusaurus development server, which allows updates to website files to be displayed in the browser in real time. It will not produce a `build` directory with build artifacts. | ||
| 1. Run `pnpm start` from the repository root to start the development server. | ||
| 2. Preview the website at `localhost:3000` in your browser. | ||
| 3. Press `Ctrl+C` to stop the preview. | ||
| - [**Local Build**](https://docusaurus.io/docs/installation#build): This option will do a production build, putting artifacts in the `build` directory. This can still be previewed locally, but will not automatically reflect changes to website files. | ||
| 1. Run `pnpm build` from the repository root to build the content. | ||
| 2. Run `pnpm serve` to preview the built website locally. | ||
| 3. Preview the website at `localhost:3000` in your browser. | ||
| 4. Press `Ctrl+C` to stop the preview. | ||
| ### Contributing Your Modifications | ||
| Fork the [apache/ozone-site](https://github.com/apache/ozone-site) repo and follow the same steps as the main [Ozone contributing guide](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md#contribute-your-modifications) to create a pull request against the [apache/ozone-site](https://github.com/apache/ozone-site) repository. the target branch for the PR should be `HDDS-9225-website-v2` for changes targeting this new unreleased version of the website. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters