Thanks Wei-Chiu, nice to see another docusaurus site. I looked around at a
high level and had some suggestions, although I did not read through or
test all the content.
- The homepage is still using the stock docusaurus icons. We can use the
ones from the original Ratis homepage.
- The accent color is also still the default green. We can match it to
the Ratis logo.
- The Blog section looks like a duplicate of the download/release
section. We can probably remove the docusaurus blog plugin in this case.
- The section called “Overview” in the header should probably be called
“Docs” or “Documentation”.
- Related to the sections under the docs:
- “Overview” and “About Apache Ratis” should be the same page.
- “Getting Started” doesn’t need the “(Detailed)” disclaimer. There’s
no other “Getting Started” page.
- I recommend using a README.mdx file to create a landing page for
each docs section so sections can be linked directly like this
<https://ozone-site-v2.staged.apache.org/docs/core-concepts/>. See
step 4 here
<https://github.com/apache/ozone-site/blob/HDDS-9225-website-v2/CONTRIBUTING.md#documentation-sidebar>
.
- It looks like currently the first page in each section is the
default landing page for a section, which creates strange URLs.
- For example, neighboring pages “Ratis-shell CLI” and
“Read-After-Write Consistency Support” have the corresponding URLs
https://jojochuang.github.io/ratis-site/docs/cli and
https://jojochuang.github.io/ratis-site/docs/features/read-after-write
despite both being subsections of “Features”
- What are the long term plans to keep the metrics and config key
tables up to date with the code? In Ozone we had looked at
auto-generating
the tables from the source.
Definitely check out the v2 Ozone site and steal whatever pieces you like
from there. Some of the general changes that would be good to take are:
- Most of the contributing guide
<https://github.com/apache/ozone-site/blob/HDDS-9225-website-v2/CONTRIBUTING.md>,
which covers general docusaurus topics at various levels.
- CI checks and docker based build. I don’t think any of that is Ozone
specific.
- Styling or layout of headers and footers
- The dropdown for docs versioning (currently only has one option in the
staging site)
Ethan
On Sat, Jul 19, 2025 at 1:10 PM Wei-Chiu Chuang <[email protected]> wrote:
> Hi Ratis community,
>
> I wanted to understand Ratis more but the documentation is pretty lacking.
>
> I spent a few hours on Friday night to come up with a documentation page
> for Ratis: https://jojochuang.github.io/ratis-site/docs/overview
>
> It's still quite rough. Contents were migrated from the current site, and a
> few new pages generated from Gemini. But just like to get an
> early feedback: are there other notable features and concepts that are
> missing?
>
> Also feel free to check out the main page:
> https://jojochuang.github.io/ratis-site/
>
> Cheers,
> Weichiu
>
