You are viewing a plain text version of this content. The canonical link for it is here.

Posted to issues@mahout.apache.org by "ryankert01 (via GitHub)" <gi...@apache.org> on 2026/01/20 12:31:42 UTC

[D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

GitHub user ryankert01 created a discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

### **Context**

Following our recent community call, we discussed the need to modernize our documentation infrastructure. The goal is to make it easier for contributors to write documentation while maintaining a high-quality, searchable website. Based on our conversation, I’m proposing we adopt **Docusaurus** and implement a specific documentation sync workflow.

### **The Proposal: Docusaurus**

I propose we move our website/documentation framework to **Docusaurus**.

* **Why:** It is a React-based static site generator that handles Markdown-to-HTML beautifully. It is developer-friendly, provides excellent SEO, and supports versioning.
* **Ease of Use:** As discussed, it allows us to focus on content in Markdown without needing to manage complex HTML/CSS layouts manually.

### **Documentation Workflow: The "Sync" Approach**

To keep the repository clean and contributor-friendly, I'd like to recreate a workflow previously used in the `gofannon` project:

1. **Source of Truth:** All documentation will live in a top-level `/docs` directory in the main branch.
2. **Build Process:** During the site build, a script will copy the contents of `/docs` into the `/website` directory.
3. **Reference:** We can adapt the sync script used here: [[sync_docs.py (gofannon)](https://github.com/The-AI-Alliance/gofannon/blob/2eaf7d22a80f4ed8794c02b074ccda137b51ea0b/website/scripts/sync_docs.py)](https://github.com/The-AI-Alliance/gofannon/blob/2eaf7d22a80f4ed8794c02b074ccda137b51ea0b/website/scripts/sync_docs.py).

### **Architectural Decision Record (ADR)**

In the spirit of preserving project history and the "why" behind our technical choices, I also propose we can update our design with an **ADR**. This ensures that future maintainers understand our reasoning for choosing Docusaurus and this specific sync logic, preventing the "deep-magic" knowledge gaps that can occur during transitions.

### **Seeking Community Feedback**

I’m opening this discussion to the community for feedback:

* Are there any concerns with using a React-based framework like Docusaurus?
* Does anyone have alternative suggestions for the sync workflow?
* If there is general consensus (or "lazy consensus"), I am happy to lead the initial setup and migration.

I look forward to hearing your thoughts!

GitHub link: https://github.com/apache/mahout/discussions/882

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "rawkintrevo (via GitHub)" <gi...@apache.org>.

GitHub user rawkintrevo added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I support this. Jekyll was good for what it was when it was (and still is). 

React sites are prettier, but if they introduce too much overhead, not worth it. But as everyone and their cat can vibe a web ui now, that maintenance overhead is significantly reduced. 

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15550286

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 edited a comment on the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I'll probably use an agent to do a POC with the migration plan, so we can review the plan along with some displays. cc @rawkintrevo 

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15561092

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I think it is a great idea and maybe we can also let some of the new contributors to work on this? like @viiccwen for example? He kind of want to have more impact in Mahout but there's not much to do left in QDP

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15551735

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I am into migrating into a new version of website? I think this can be a post PoC thing and we can involve more new contributors to work on it in GSoC. If there's not enough people to work on it, we can do it in post PoC ourselves. In general I think we can like put it aside and focus on the release. But I think it is a necessary work since I think if we want users like scientist or researchers to use it, we need a visual appealing doc for website. Because maybe not every researcher knows how to use it by reading the code?

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562410

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "krishna-dave206 (via GitHub)" <gi...@apache.org>.

GitHub user krishna-dave206 added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I agree with y'all. This would help us cover both the agendas: "Easy to maintain" and "Prettier"

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15555337

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

hmm I think maybe open it and have more time for people to review it? like having like 4~5 people reviewed and approved?

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562734

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I think keep the current docs might be the safest play because migrate means a lot of work. But at the same time, [Docusaurus](https://docusaurus.io/blog/releases/3.9) have those nice features like versioned docs,  styles that is nice, and many others.

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562360

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I'll probably use ai to do a POC with the migration plan.

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15561092

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "magsol (via GitHub)" <gi...@apache.org>.

GitHub user magsol added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

+1 from me. Love the "single source of truth" approach. The only bit of feedback I'd give is that docusaurus is a BEAST that will do absolutely everything you need it to, and then some. So be prepared for initial setup and config to be a heavier lift than you're expecting, but life after that should be pretty nice. 

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15565275

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "rawkintrevo (via GitHub)" <gi...@apache.org>.

GitHub user rawkintrevo added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

For what it's worth- it's docs/website which carries a significantly lower bar for reviewing. If something breaks, oh well just go fix it. It's not a critical dependency or anything. Also, on this PR its going to just be a bunch of boiler plate code anyway. I did `gofannon earlier today.  Also, don't forget to disable the website build in your initial commit (so the old site remains while we build the new one. (Or do the whole thing on a branch)
 

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15576586

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping edited a comment on the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I think it is a great idea and maybe we can also let some of the new contributors to work on this? like @viiccwen for example? He kind of wants to have more impact in Mahout but there's not much to do left in QDP.

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15551735

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 edited a comment on the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I'll probably use ai to do a POC with the migration plan. cc @rawkintrevo 

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15561092

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

Closing this since this is completed.

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-18547607

----
This is an automatically sent email for dev@mahout.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I can write a migration plan first to see what's the overhead looks like.

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15554800

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I agree we need a good planning for docs. For my experience in KubeRay, I tend to go see the docs first as I am exploring a new area I haven't touch since the codebase is huge and you don't know whether you should look at Ray or KubeRay.

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562345

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "rawkintrevo (via GitHub)" <gi...@apache.org>.

GitHub user rawkintrevo edited a comment on the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

For what it's worth- it's docs/website which carries a significantly lower bar for reviewing. If something breaks, oh well just go fix it. It's not a critical dependency or anything. Also, on ~~this PR its going to just be a bunch of boiler plate code anyway. I did `gofannon` earlier today.  Also, don't forget to disable the website build in your initial commit (so the old site remains while we build the new one. (Or do the whole thing on a branch)~~ (edit) you are actually getting a bunch of it in the first shot
 

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15576586

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

Don't get me wrong. I'm not worried about the engineering power, because I kinda near finish migration locally. I'm just worried about it probably will be a super big PR and that's hard to review.

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562678

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping edited a comment on the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I am into migrating into a new version of website? I think this can be a post PoC thing and we can involve more new contributors to work on it in GSoC. If there's not enough people to work on it, we can do it in post PoC ourselves. In general I think we can like put it aside and focus on the release. But I think it is a necessary work since I think if we want users like scientist or researchers to use it, having a visual appealing doc for website is a plus? 

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562410

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping edited a comment on the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I am into migrating into a new version of website? I think this can be a post PoC thing and we can involve more new contributors to work on it in GSoC. If there's not enough people to work on it, we can do it in post PoC ourselves. In general I think we can like put it aside and focus on the release. But I think it is a necessary work in the long term maybe?

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562410

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

I think it's too late to be part of this release. tho, I get some demos. As I dive in, I would say it need a good planning for docs placement. Today's documents is kinda scattered which add complexity to the migration.

<img width="1458" height="800" alt="截圖 2026-01-22 凌晨12 35 22" src="https://github.com/user-attachments/assets/83023319-c468-4a5f-93df-ba9e06046eb9" />
<img width="1469" height="803" alt="截圖 2026-01-22 凌晨12 35 11" src="https://github.com/user-attachments/assets/53a506b4-bcf4-40fa-a58d-463826ba6086" />


GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562275

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

Great advice! I think disable website build is a great solution!

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15576599

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "400Ping (via GitHub)" <gi...@apache.org>.

GitHub user 400Ping added a comment to the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

It's alright then, Vic was asking if theres anything more impactful to do like last week. We could just mentor him at GSoC. Nice looking website btw.

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15562315

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "rawkintrevo (via GitHub)" <gi...@apache.org>.

GitHub user rawkintrevo edited a comment on the discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

For what it's worth- it's docs/website which carries a significantly lower bar for reviewing. If something breaks, oh well just go fix it. It's not a critical dependency or anything. Also, on this PR its going to just be a bunch of boiler plate code anyway. I did `gofannon` earlier today.  Also, don't forget to disable the website build in your initial commit (so the old site remains while we build the new one. (Or do the whole thing on a branch)
 

GitHub link: https://github.com/apache/mahout/discussions/882#discussioncomment-15576586

----
This is an automatically sent email for issues@mahout.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@mahout.apache.org

Re: [D] RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow [mahout]

Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.

GitHub user ryankert01 closed a discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow

### **Context**

### **The Proposal: Docusaurus**

I propose we move our website/documentation framework to **Docusaurus**.

### **Documentation Workflow: The "Sync" Approach**

To keep the repository clean and contributor-friendly, I'd like to recreate a workflow previously used in the `gofannon` project:

### **Architectural Decision Record (ADR)**

### **Seeking Community Feedback**

I’m opening this discussion to the community for feedback:

I look forward to hearing your thoughts!

GitHub link: https://github.com/apache/mahout/discussions/882

----
This is an automatically sent email for dev@mahout.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@mahout.apache.org