MkDocs Rails

Easy MkDocs setup for Rails development.

Adds Material for MkDocs (or vanilla MkDocs) to your Rails app with one command. Perfect for internal documentation, API docs, and developer guides.

Add to your Gemfile:

gem "mkdocs_rails", group: :development

Then run:

bundle install
rails generate mkdocs_rails:install

# First-time setup (creates a local Python venv and installs packages)
bin/docs setup

# Start the MkDocs development server
bin/docs serve
# Visit http://localhost:8000

# Build static docs directly into Rails public/docs
bin/docs publish

# Clean the public/docs directory
bin/docs clean

The publish command outputs a production-ready static site to public/docs, automatically served by Rails at:

http://localhost:3000/docs/

The trailing slash (/) is required for the static docs to display correctly.

• Generator creates complete MkDocs project structure
• Material for MkDocs theme by default (or use --vanilla for plain MkDocs)
• Automatic Python virtual environment management
• Auto-detects and installs plugins from mkdocs.yml
• Simple bin/docs script for common tasks

rails generate mkdocs_rails:install --vanilla

Edit docs/mkdocs.yml:

plugins:
  - search
  - awesome-pages

Most plugins follow the convention mkdocs-{name}-plugin. For custom package names, create docs/.mkdocs-packages:

plugins:
  awesome-pages: mkdocs-awesome-pages-plugin
  glightbox: mkdocs-glightbox

Then run bin/docs setup to install.

Bug reports and pull requests are welcome.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am "Added some new feature")
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

The gem is available as open source under the terms of the MIT License.