Dokno
Dokno (e.g., "I do' kno' the answer") is a lightweight Rails Engine for storing and managing your app's domain knowledge.
It provides a repository to store information about your app for posterity, such as term definitions, system logic and implementation details, background for past system design decisions, or anything else related to your app that would be beneficial for you and your users to know, now and in the future.
Installation
Add this line to your application's Gemfile:
gem 'dokno'
From your app's root folder, run:
$ bundle
Run Dokno migrations to add the Dokno article and category tables to your db:
$ rake db:migrate
Mount Dokno in your /config/routes.rb
at the desired path:
mount Dokno::Engine, at: "/help"
Initialize Dokno configuration:
$ rails g dokno:install
To enable in-context articles in your app, add the supporting partial to the bottom of your application's app/views/layouts/application.html.erb
, just above the closing </body>
tag:
<%= render 'dokno/article_panel' %>
Configuration
Dokno Settings
Running rails g dokno:install
creates /config/initializers/dokno.rb
within your app, containing the available Dokno configuration options. Remember to restart your app whenever you make configuration changes.
Articles
Accessing Articles
Each article is accessible via its unique slug, either through its permalink to view the article within the Dokno site, or by an in-context flyout link within your app.
Articles can be assigned to 0+ categories, and categories can be "infinitely" nested.
Authoring Articles
By default, any visitor to the knowledgebase site can modify data.
See /config/initializers/dokno.rb
to link Dokno to the model in your app that stores your users. This will allow you to restrict Dokno data modification to certain users, and to include indentifying information in article change logs.
Articles can include basic HTML and markdown, and you can configure a starting template for all new articles. See /config/dokno_template.md
.
Usage
Accessing the Knowledgebase Site
The Dokno knowledgebase is mounted to the path you specified in your /config/routes.rb
above. You can use the dokno_path
route helper to link your users to the knowledgebase site.
<a target="_blank" href="<%= dokno_path %>">Knowledgebase</a>
In-Context Article Links
Each article has a unique slug
or token that is used to access it from within your app. Use the dokno_article_link
helper to add article links.
Clicking a link fetches the article asynchronously and reveals it to the user via flyout panel overlay within your app.
<%= dokno_article_link({link-text}, slug: {unique-article-slug}) %>
Dokno Data Querying
You typically won't need to interact with Dokno data directly, but it is stored within your database and is accessible via ActiveRecord as is any other model.
Dokno data is Dokno::
namespaced and can be accessed directly via:
Dokno::Article.all
=> #<ActiveRecord::Relation [#<Dokno::Article id: 1, slug: "uniqueslug", ... >, ...]
Dokno::Article.take.categories
=> #<ActiveRecord::Relation [#<Dokno::Category id: 1, name: "Category Name", ... >, ...]
Dokno::Category.all
=> #<ActiveRecord::Relation [#<Dokno::Category id: 1, name: "Category Name", ... >, ...]
Dokno::Category.take.articles
=> #<ActiveRecord::Relation [#<Dokno::Article id: 1, slug: "uniqueslug", ... >, ...]
Dokno::Category.take.parent
=> #<Dokno::Category id: 2, name: "Parent Category Name", category_id: 1, ... >
Dokno::Category.take.children
=> #<ActiveRecord::Relation [#<Dokno::Category id: 3, name: "Child Category Name", ... >, ...]
Dependencies
Dokno is purposefully lightweight, with minimal dependencies.
It has two dependencies: the redcarpet gem for markdown processing, and the diffy gem for change diffing, neither of which have further dependencies. Both are excellent.
Pull Requests
Contributions are welcome.
Proposing a Solution
Before starting on a PR, check open issues and pull requests to make sure your enhancement idea or bug report isn't already being worked.
If not, open an issue to first discuss the proposed solution before beginning work.
Providing Proper Test Coverage
Before submitting your PR, make sure that all existing specs still pass, and that any new functionality you've added is covered by additional specs.
To run the test suite:
$ bundle exec rspec
Hat Tips
-
tailwindcss
- CSS framework
-
diffy
- Text diffing Ruby gem
-
Feather Icons
- Icon library
-
redcarpet
- Markdown parsing Ruby gem
License
The gem is available as open source under the terms of the MIT License.