Can we change the ruby on rails website documentation?

The Ruby on rails documentation is really hard to navigate, its a lot of stuff and everything is everywhere and I cant find what I’m looking. Hoping for new Upgrade documentations like the documentation used by vuejs or nuxt4.

1 Like

I got accidentally involved with recommending and using a static site generator for prog lang community marketing / community / tutorial website last year. At that time, I was leaning towards 11ty, as it stays with static html, but let’s you use all the html and markdown libraries on npm. I originally wanted to choose hugo, so that I could avoid depending on npm world. I ended up choosing nextjs to accommodate other peoples’ desire to have more interactivity and javascript.

I would probably choose docusaurus v2 for a site that only had tutorials and didn’t need marketing or community pages. I don’t like npm, but since a large chunk of the dev world is using javascript to create html and css for single page apps as well as for markdown rendering, it feels like you have the access to the largest potential set of markdown and html libraries with npm (rather than static site tools using go, python, ruby). I liked 11ty’s philosophy, but docusaurus has a nice set of built in features for documentation. Docusaurus v2 uses the complex hydration with client side interactivity which 11ty shuns, but it’s probably worth dealing with it.

1 Like

I really don’t care what framework to use, the most important is to make users or even new users to easily navigate in the documentation. Before the current guide is not that really good.

1 Like

I haven’t formed an opinion on the current navigation yet.

I agree that framework doesn’t matter too much, as long as it won’t go obsolete too fast. I mentioned the framework because I imagine the first step in writing new docs and building nav would be selecting some directory organization and creating markdown files, and once you pick a framework, you can start working on those according to the framework’s organization rules.

1 Like

I enjoyed the Guide, so I’m probably biased. What exactly were you looking for and didn’t find?

1 Like

I was actually able to find what I’m looking, but to be able to go to different pages, the page needs to reload.

I mean the guide is fine, its actually easy to use but the time it reloads when going to different pages.

FWIW, Rails guides and APIs are statically generated and served by NGINX. We even generate the compressed versions in the file system for NGINX to serve directly (gzip_static on).

1 Like

It will help a lot if there is a search box at the top

1 Like

Yup I think that is also a good suggestion.

So what you were looking for is actually Single-Page Application (SPA). I’m not sure how difficult it is to generate an SPA from the current Guide, but I myself enjoys the simplicity of static websites. For any one who plan to build SPA, I suggest:

  1. Do it right, the first time. Accessibility needs to be implemented in SPA, while for static websites the browser did most thing correctly. An example: most navigation should behave like “links”, e.g. I can “open in a new tab”, or hover my mouse on the link to preview the target URL.
  2. Possibly keep the static website as a fallback for clients without JavaScript (such as NoScript users).

By the way, what’s “nuxt4”? I only found Nuxt3.

1 Like

yeah, I agree with your points, I would probably like to volunteer but I am so busy on my current Job.

wait, nuxt4? I think their is no nuxt4 yet. Nuxt3 is still on RC.

There is a PR to add search to Rails Guides:


Transitioning the guides site to SPA doesn’t bring any additional value to the guides site, my preference would be to keep it as @fxn mentions. SPA is just going to add more tooling for effectively the same result that’s currently there, a page refresh is fine. This is also what vuejs and nuxt4 do as well, statically generated pages.

Adding search would be helpful though, I agree on that one.

@fxn What about the open source plan with Algolia for search and DocSearch? Algolia for Open Source | Algolia

Algolia opened a PR a while back and we had a discussion.

I have paid for the servers that host Rails documentation and Rails Contributors since I purchased them many years ago. Why? Because it is fair that if you get help from a company, you give credit for it, for example with a logo. OK, I don’t want to push brands into the minds of Rails programmers, so I solved this personal dilemma with money.

So, the summary of the PR was: That’d be nice, as long as there’s no branding. They said, but branding is fair, and I said, yes, but I did not ask for this patch, I am only saying under which conditions it would be accepted. And that was the end of it.

Now, I don’t pay for the servers anymore, so whether to go for that solution or not I leave to the rest of the core team that might be interested in this and if they go with that solution it’ll be fine with me.


@fxn Ah gotcha, good to know. Are the servers running PG? I’d assume not and it’s just nginx serving up those files. Is the deploy process something along the lines of a git pull and then rake guides:generate?

@nickhammond exactly.

We have a webhook in GitHub that triggers an action in the docs server on every push.

That action then updates the local checkout, generates edge docs (API and guides), if a new stable tag version is detected, generates stable docs for that release (API and guides). Also, Rails Contributors updates.

Documentation is compressed HTML files on disk served by NGINX, no database.

1 Like

@fxn Is the PR above feasible? Is execjs available at build time already? I noticed that’s required in the new search_index.rb file.