matuzalemsteles
commented
6 months ago Just an update on this, last week I found a library called mdxts that brings some resources for documentation that we could use here that solves some problems I found, so we can keep some things:
- Organization of current documents can be kept in packages
- We don't need to maintain the manual sidebar
- We can improve the code block experience by inferring component types
- We don't need to create the Table API from scratch
ethib137
https://clay-clayui-com.vercel.app
Well this is a POC that implements the design that I presented a few years ago but still incomplete from clayui.com with the idea of also bringing better documentation for taglibs and improving the existing documentation for React, HTML, CSS and tokens... many of these details were not implemented because it requires a little more work, mainly due to the way we organize the documentation files, which deviates a little from Next.js pattern.
But the idea here is to demonstrate how we can simplify the current implementation today of clayui.com by migrating from gatsby with next.js. There are some things that we would need to implement due to the way we deal with organizing files for documentation. I also didn't go ahead with the integration with LXC because I would need to decide first how we would organize the documents and this affects the route structure but in the end this would be a dynamic route making a call to LXC this would be simpler than in Gatsby which we need organize the data before creating the page.
Another detail is that we can get rid of the thousands of plugins that exist in gatsby that we had to create, which created high complexity for new developers if they want to change or add new things. Next.js also has a better build time because it is incremental, which is a huge benefit for those of us working on documentation.
ISR
ISR is a feature not necessarily from Next.js and Vercel but something that is implemented as a feature and is easy to use, this means that even if we have dynamic routes with LXC they can become static routes and as soon as some content changes we can trigger a revalidation of this page in the background dynamically without the need for a build. There are also other ways of revalidating the page cache such as time, we can define a time if we want to make things simpler, that would be an option.
File System
Well, Next.js creates routes based on the file system within the
appfolder, this is a rule for not only creating routes but also for features such as route streaming, error catching, loading... how we organize documents of the components in each package this would maybe change a little, I'm not sure if it would be possible to do it the same way we do in Gatsby this would change some webpack configs I think this is possible but I don't know how the document routes would work, I would need to investigate this more in depth.MDX
All documents are treated as MDX files so we would move all md files to mdx, we already use mdx files on the current site this wouldn't be a problem.
Currently the Sidebar is created manually, we would need to implement the mechanism to obtain this dynamically so as not to need to add it manually or we can keep it manual so we can organize it the way we want as it is in the DEMO.
Platform
Well, using Next.js also means that we would have to use Vercel unfortunately if we want to avoid problems with builds or surprises... one point is that Vercel's costs seem to be better than Netlify.
Design
This Design is something I worked on some time ago and presented in a document about restructuring the documentation with the intention of improving the Table API, taglibs and component documents.
An important point about this was the idea of building a Table API with more information and also allowing developers to better explore what we expect from the data in a prop.
Another important part is that I am dealing with the website design in a different way with the isolation of the website's CSS to the Clay CSS, this prevents the website's CSS from impacting the document or things related to Clay, we have already had problems with this in clayui .com and I realized that there are still some very subtle ones.