I’d like to formally request that the Bricks Builder documentation be hosted on GitHub, either as a primary repository or as a mirrored version of the existing documentation. While this wouldn’t necessarily replace the current documentation system, it would provide significant additional value in today’s AI-enhanced dev tooling.
Key Benefits
Enhanced AI Integration Today’s developers increasingly leverage Large Language Model (LLM) tools like ChatGPT and Claude to streamline their workflows. These AI assistants can directly connect to GitHub repositories through Model Context Protocol (MCP) and similar technologies, allowing developers to have interactive conversations about codebases and documentation stored there.
Unified Developer Experience By having both code and documentation in the same ecosystem, developers can maintain context while switching between implementation details and documentation guidance, creating a more seamless development experience.
Community Contributions GitHub’s established contribution workflow (issues, pull requests, discussions) would enable the community to more easily suggest improvements, corrections, or expansions to documentation, potentially increasing both quality and coverage.
Version Control and History Documentation changes would be tracked with the same robust version control that GitHub provides for code, making it easier to understand how documentation has evolved alongside the software.
Implementation Suggestions
The documentation could use GitHub Pages or a similar system for rendering
Pull requests could be reviewed by the core team to maintain quality standards
Existing documentation systems could pull from the GitHub repository as a source of truth
Conclusion
In summary, hosting Bricks Builder documentation on GitHub would significantly enhance its accessibility and utility, particularly for developers who already use AI assistants as part of their workflow. This represents a forward-thinking approach that acknowledges how modern development practices are evolving in the age of AI tools.
Seems like an extra work that would only benefit a specific group of people. You can still use your AI and feed info onto it from the current academy. Stop being lazy.
It seems like you don’t understand the nature of the request or the benefit of it, or perhaps you don’t use the tools and don’t see the value and that’s okay! Thanks for the comment.
Putting up an initial github repo as a proof of concept - GitHub - DigiSavvy-Inc/bricks-builder-docs
I have a python script that scrapes the content and converts each page to markdown and I used a bash script to organize things. so it’s not a 1:1 match structurally to the academy site.
Definitely an interesting idea. I looked at your proof of concept. I’m not a heavy user of GitHub, but from the perspective of trying to review documentation as an end user building a site, I personally don’t think it’s the right solution as navigation is more challenging.
I was also curious, in your key benefits, points 1 and 2, who specifically does that help? Bricks Developers, plugin developers integrating with bricks, end users/developers building sites?
I definitely agree with the great community supporting bricks that point 3 and 4 of using GitHub would greatly improve the content of the academy without the Bricks Team doing as much of the heavy lifting.
I think it comes down to the target audience, I think if it’s for developers of tools related bricks or advanced website development by experienced devs, then having it just on GitHub would probably work. But a broader audience just building sites would probably find the documentation difficult to access and use from GitHub directly.
Bottom line, Bricks documentation could stand for some improvements and I believe they said work would be done on that after 2.0 is released. Maybe this thread will give them some other ideas to consider in order to get there, if they don’t have a concrete plan already.
Thanks @Mundy - the point that’s being missed here is that you don’t need to look at Github for documentation. The idea here is to host documentation in Github so you can use tools like Claude or ChatGPT to instead chat with the documentation. Since there are Github integrations that allow these tools to interact with Github hosted repos.
Generally speaking, when you are researching a solution in a knowledge base you search, you click, maybe you find, maybe you don’t. Or if you do find the solution maybe you don’t understand it well enough.
Having an LLM interface to your documentation allows users to ask questions of your documentation, thus requiring less search, better understanding, less hallucinations since the documentation is a source of truth for answers. Often, in the case of bricks, I use Claude to help with custom tags and the number of times that Claude hallucinates is staggering. When I started pointing it (Claude) at my codebase locally and on Github I found better reliability.
So this proposal is not meant to replace the online documentation provided. This proposal is not intended to have people search docs on Github. This proposal is intended to provide a touchpoint for people to interface with Bricks Builder documentation through their preferred LLM client.
Interesting idea. Wouldn’t scrapping the website and storing the data in a vector database work as well if the Bricks add a chat bot linked to that vector database?
I do agree chatting with a chatbot would be better than searching for an answer via their website.
@seaj1one - perhaps. I don’t know, since I’ve never tried it. I don’t see any reason to scrap the existing docs/academy website. My proposal is intended as a companion to the Bricks documentation. My proposal allows for folks to use the tools and resources they know best to interface with Bricks KB.
This is interesting idea. Have you done this with other plugin documentation?
I’m interested in your workflow to feed the github repo to AI. What do you use to allow claude/chatgpt to read the documentaion in github?
@wotimama - Bricks is the first I’ve done this with. I’m working on it now. My process needs refinement but here’s what it looks like:
Scrape website links. Sitemap.xml or using Screaming Frog to get an csv would work well.
Run a Python script that scrapes the pages outlined in your csv/xml file, converts the content to markdown.
Create a bash script to organize the content
Create a github repo, bob’s your uncle!
Now, I use Claude for most of my stuff, it’s my preferred tool. I use Claude Code, their agentic coding offering, to create the python script and bash script to organize content. I’ll also use it to generate readme files for each directory and to create an index of the content for easier consumption.
You can use MCP to connect your preferred LLM to a github repo. Or int he case of Claude, Github is a built-in integration so you can tell your LLM client to look for a solution but to only use a specific repo to produce a solution. This greatly reduces hallucinations.
Another resource to be aware of for LLMs - https://context7.com/?q=wordpress - contex7 stores documentation for various product apis, general documentation and more. Easily interfaced with via MCP. Bricks would do well to get their docs up there but it starts with creating a repo for it.