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.

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' %>

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.

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.

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.

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>

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}) %>

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", ... >, ...]

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.

Contributions are welcome.

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.

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

• tailwindcss
  • CSS framework
• diffy
  • Text diffing Ruby gem
• Feather Icons
  • Icon library
• redcarpet
  • Markdown parsing Ruby gem

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