Doctor : An Open Source Documentation Server

MinIO -

Doctor uses markdown (MD) format for documentation and github for version control. Use Doctor to aggregate multiple MD files from across repositories into a single documentation site. Doctor is licensed under Apache V2.0 license.

See a live demo : https://docs.minio.io

docs.minio.io

Why we built Doctor

We wanted a documentation server to simply organize and render our markdown pages from github. We loved markdown since it was easy for our non developers to create/edit documentation. We needed to involve the community in making our documentation better. And finally we needed a docs site which does not look like a github source repository. After evaluating various frameworks, CMS solutions, cloud hosted platforms and TeX/DocBooks based tools, we ended up building Doctor.

Deploy Doctor

Doctor can be easily deployed on heroku for production and locally for development.

Local Deployment

  • Install Ruby 2.2.2.
  • Install Rails 4.2.4
  • Install Postgres and start Postgres.
  • Type the commands below in your terminal
> git clone https://github.com/minio/doctor.git
> cd doctor
> bundle install
> rake db:drop
> rake db:setup
> rails s

Visit http://localhost:3000

Heroku Deployment

  • Create a new heroku app
  • Make a fork of https://github.com/minio/doctor repository
  • Using the Deploy tab in heroku, connect the github fork to your heroku app
  • Click ‘deploy branch’ to successfully build and deploy Doctor for your needs.
  • Type the commands below in your terminal
> heroku run rake db:drop
> heroku run rake db:setup
  • Visit the heroku app in your browser.

Manage Documents

  • Create Categories.
  • Create Documents.
  • Paste the full raw link to the MD files from github when creating documents.
Copy Raw Link to MD files
  • Associate each document with a specific category. Save and you are done.
Point to the raw github MD file and associate a category

Community Collaboration

Collaboration was another key requirement for us. We take a non trivial stand when it comes to having our community contribute to our project. So we provide the “Suggest Edits” feature in Doctor where any developer that uses our docs can suggest changes by clicking on Suggest Edits button and sending us a simple PR with their changes. Github workflow is then used to manage the submitted changes to documents. This was a feature we could not find in Cloud Hosted documentation solutions, Content Management Systems or Frameworks.

Customization

One can edit project details from within the dashboard and change project name, configure links in the header and the footer. See screenshot below :

Brand Customizations

Project Settings

A complete style guide is also available here.

Conclusion

Doctor is designed to be minimal. Please feel free to fork this project. If you develop any cool features, please consider sharing them with our community. We’d love to see your Pull Request.

Contribute to Doctor at : https://github.com/minio/doctor

Doctor enhancements and issue list can be found at https://github.com/minio/doctor/issues