Our great sponsors
-
project-bot
:octocat: Automatically add and move Issues/Pull Requests on a Project board (by philschatz)
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
vale-action
:octocat: The official GitHub Action for Vale -- install, manage, and run Vale with ease.
-
just-the-docs
A modern, high customizable, responsive Jekyll theme for documentation with built-in search.
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
pages-gem
A simple Ruby Gem to bootstrap dependencies for setting up and maintaining a local Jekyll environment in sync with GitHub Pages
Be sure to look through the sample GitHub repository for the Rails app and sample Jekyll site we created in this article. The repo includes sample issues and a pull request, as well as labels. It also has an automated GitHub Project and a sample pull request template for authors, reviewers, and maintainers to follow when adding documentation to the code base.
For larger projects that include more than just docs, use the project-bot GitHub App to set up automation rules. For example, adding a specific label or assigning a specific reviewer would trigger automatic card movement. Alternatively, you can integrate documentation management into your larger project management workflow using a tool like Jira.
There is also a popular prose linter called Vale, which has extensions in VSCode and other editors.
Vale action
Markdownlint action
More complex documentation can be created using RDoc or other syntax (see the YARD documentation), but we'll stick with the existing documentation here.
This creates a /docs directory containing a minimal Jekyll site (the default is a blog theme called Minima). You can use this as the base for your custom Jekyll docs site. Alternatively, you can install a docs theme, such as just-the-docs, which comes with sidebar navigation and site search functionality.
Continuous publication is convenient for docs sites because the live site can be updated automatically when changes to docs are approved and merged into the repository. This tutorial uses Netlify for this purpose, but other tools are available, such as GitHub Pages, GitLab Pages, and Firebase.
Continuous publication is convenient for docs sites because the live site can be updated automatically when changes to docs are approved and merged into the repository. This tutorial uses Netlify for this purpose, but other tools are available, such as GitHub Pages, GitLab Pages, and Firebase.