I have a gem, tabulo that is getting to the point where the README is pretty long, and contains more than just a bare introduction to the gem. It really acts as a user manual for the gem. I like to have a README that's pretty substantial, as I think this is much more accessible than just pointing to the rubydocs and leaving it at that. However, it bothers me that there is no sidebar navigation—meaning readers have to keep jumping back to the top to see the contents. It also feels like the README is getting too long for just one page.

Lately I've been looking at GitBook and wondering whether to migrate the content of the README there. It provides a very nicely formatted layout with sidebar navigation, as well as a prompt that lets users easily suggest edits to the documentation. See the GitBook for FoalTS, as one example.

My question is: Do the readability and navigability benefits of putting the user guide in GitBooks (or something similar) outweigh the "accessibility" benefits (for want of a better word) of having the user guide simply be the GitHub project README? Having everything in the README means that once users (or potential users) land on the GitHub repo, the "complete" guide to using the gem is "zero clicks" away; it can be read through continually simply by scrolling down. But it's not as navigable or as slick as GitBook. I'm trying to weigh these things up. If anyone has any experience, thoughts or feedback on this, that would be greatly appreciated.

Hi all. For al my project I have always used Github README documentation. But since I'm developing a bigger project I need something more powerful or structured that helps me to write down all the parts of my framework (but I don't want to develop a dedicated documentation website at the moment). What do you suggests?

Here some alternatives I am considering:
- Github README - with dedicated folder and .md files
- GitBook

Please add your experience, tools and suggestions taking into account that I'm developing a web framework and I need also to explain APIs.

I've been using GitBook for documentation in some of my projects, but I'm increasingly running into limitations with their free tier, and I'm not a fan of relying on their cloud service. I'd prefer to self-host a similar solution for better control and customization.

Ideally, I'm looking for a self-hosted alternative that offers:

• Markdown support

• Clean, modern UI like GitBook

• Easy navigation/sidebar structure

• Version control integration (Git preferably)

• Good search functionality

Ability to collaborate with others I know there are options like BookStack, DokuWiki, and MDBook out there, but I'd love to hear from anyone who's made the switch from GitBook to a self-hosted solution. What worked well for you? Any implementation challenges I should be aware of?

Thanks in advance!

UPDATE: Thanks for all the suggestions—super helpful!

Just wanted to mention that I ended up trying out Apidog's self-hosted docs and it’s been a really solid alternative to GitBook for my needs. It supports Markdown, has a clean and modern UI, and the sidebar/navigation setup feels very familiar.

It also integrates with Git for version control, which was important for me, and the search has been decent so far. I’ve been using it for about 6 months now after hitting the limits of GitBook’s free tier, and I’ve been really happy with it. The self-hosting setup was pretty straightforward if you follow their guide.

If you’re looking for something GitBook-like but with more control, it’s definitely worth a look.

I'm over WordPress, I think they have gone too far with trying to make an editor that is all things to all people and I find editing to be very distracting. I am writing technical documentation and need it to be precise rather than fancy.

I really like GitBook, but I want to retain creative and hosting control.

Is there a self hosted version of something like GitBook?

Many thanks.

We love gitbook, but hate the fact the pricing is unpredictable + it's not FOSS :(, so we built something that we could use for our documentation needs. We were big fans of docusaurus and RsPress (like docusaurus but built with rust based tools) but onboarding non-technical people to use it was a pain.

Introducing kalmia! It's free (as in freedom with AGPLv3), it's pretty, it's blazingly fast. If you want to know more details about it you can read about it on our blog or just go straight to the github/docs.

PS: It's a very early stage product so there might be a few bugs/breaking changes!

Hi all. For al my project I have always used Github README documentation. But since I'm developing a bigger project I need something more powerful or structured that helps me to write down all the parts of my framework (but I don't want to develop a dedicated documentation website at the moment). What do you suggests?

Here some alternatives I am considering:
- Github README - with dedicated folder and .md files
- GitBook

Please add your experience, tools and suggestions taking into account that I'm developing a web framework and I need also to explain APIs.

Hi,

This is probably not the right subreddit, but I have no better idea.

Do you know an alternative to gitbook? I get so annoyed by this tool. It breaks all the time. The editor really sucks, makes it basically unusable and because tables are converted to html with a broken formatting I can't edit them in the code anymore. I am so pissed, it gets worse and worse.

Recently, I have created a GitBook plugin, named gitbook-mindmaps for generating mind maps with markdown format like the following snippet:

```mind
# 1
## 1.1
### 1.1.1
```

So why not use GitBook to build your document with such flexible plugins to create different interesting things with markdown, or event to doument anything?

I happened to know a site similar to Github pages, gitbook.io. But I don't get the difference of gitbook.io and gitbook.com, and how to post or sync repo to gitbook.io but not gitbook.com. But googling stackoverflow, github, Reddit didn't help me a lot, but nearly no info about gitbook.io. Is the service still alive..? So, anyone knows how to use gitbook.io? Thanks.

Hello everyone,

I really like gitbook, I love the look, the features, and being able to use markdown. I am on the personal plan and was wondering does anyone find the 10 public and private spaces limiting? I have tried notion among others but don’t find them to have the same features and organization that gitbook does. I would be more than happy to pay for a personal plan that offers unlimited spaces if they offered it.

Just published 90% of a webbook with GitBook after a couple devs interested in the project mentioned it! Anyone else publish documentation or push GitHub through to it? I'd love to see how you're formatting yours and what you're working on

We've been using GitBook for like two years and honestly it was solid. Then they announced the pricing change and... yeah, no. We're a small team and suddenly we're looking at costs that don't make sense for what we actually need.

The main thing we care about is that our API docs are easy to navigate, searchable, and don't look like they were made in 2005. Bonus points if it's not a nightmare to set up. We use Stripe's docs as the gold standard tbh.

I've been looking at Readme but haven't actually used it yet. There's also Stoplight which seems fine if you're into the whole visual API design thing, but we just want something that works. And then there's always just... building something ourselves with MkDocs or Sphinx, which feels like overkill for what we need.

Has anyone switched away from GitBook recently? What'd you land on? Curious if people are using the open source stuff or if there's something better that actually costs money but doesn't break the bank.

Also quick question for anyone still on GitBook - did the pricing actually affect you guys or did you negotiate something, because that'd be useful info too.

Hi all,

I am looking for a good tool to create, maintain et deploy our software documentation. The document would contain chapters and pages of textual explanations, images and many pieces of sample code .

Until now, we have been using dokuwiki and bookstack. But bookstack is a pain to work locally and then deploy the updated content to our online server. There is no good solution to import / export books, chapter or pages.

So, what about you ? what do you use to manage your API documentation for your customers ?

Thx

I am really not a fan of Github and I do not want to pay for Gitbook. I am a cyber professional so the whole committing code and pulling repos just isn't what I am into at the moment.

I just want to be able to document my study notes, projects with screenshots and share with others when I want.

Thanks

EDIT: Just want to thank everyone for their responses. I know most are just short and sweet "This is how I do it" but that is what I was looking for. I have a ton of new ideas and many new options to explore.

Thank you all again!

Hi,

I'm looking for some good/decent Gitbook alternatives which are open-source and based on Reactjs. My requirement is to create documentation website for my open-source projects and then host it on github pages.

Please comment down the name of the project if you know any. Thanks!