Creating Searchable Documents

This helper provides a layout that will create a nested collection of documents like this one and which are searchable via the box on the top left.

The Document Index

The application must supply a hash to describe the page index that has been built on the the left of the page. Here is the index used for this page:

index = {}
index[nil] = {
  intro: "Introduction",
  page2: "Page 2",
}
index["Topic 1"] = {
  topic1_item1: "First Item",
  topic1_item2: "Second Item",
}

The sub-hash keys describe where each document lives and what its title is, for example the document with title “Second Item” should live in _documents_root_/topic1/item2.md.erb.

By default the root is "#{Origen.root}/templates/web/docs" but this can be overridden by supplying a :root option which should describe the relative path from "#{Origen.root}/templates/web".

The Layout Helper

A layout helper is provided to include a document in the search and wrap it with the indexed layout:

% render "doc_helpers/searchable.html", index: index do

Blah blah blah

% end

The :index option is mandatory, but the following are optional:

:heading   - Each wrapped document will have the heading (e.g. "First Item") inserted at the top of the page,
             to override it supply this option. A common example would be if the topic is long and
             so an abbreviated version has been used in the index. e.g. "First Item and Other Stuff"
:topic     - Each wrapped document will have the topic (e.g. "Topic 1") inserted at the top of the page,
             to override it supply this option. A common example would be if the topic is long and
             so an abbreviated version has been used in the index. e.g. "Topic 1 and Other Stuff"
:root      - override the top-level folder containing your documents, e.g. "tutorials/guides"
:tab       - the helper should automatically work out what tab to select for each document, however
             if it is struggling for some reason you can force it by supplying the hash key from the
             index that the given document should be associated with, e.g. :topic1_item1
:prompt    - the search box prompt, by default is "Search these docs..."

Incorporating in Your Own Layout

Normally the searchable layout will be wrapped in your own application specific layout to insert your custom navigation bar, etc.

As an example here is the actual layout that has been used to generate this page:

---
title: Origen Documentation Helpers
---
<%= render "partials/navbar.html", tab: :examples %>

% index = {}
% index[nil] = {
%   intro: "Introduction",
%   page2: "Page 2",
% }
% index["Topic 1"] = {
%   topic1_item1: "First Item",
%   topic1_item2: "Second Item",
% }

% opts = options.merge(index: index, root: "examples/searchable")
% render "doc_helpers/searchable.html", options.merge(opts) do

<%= yield %>

% end

Writing Your Documents

With the layout setup, writing documents is very simple; these should normally be regular markdown that is wrapped in your layout.

The top-level header size in your document should be h3 or ### in markdown.

.html.erb files will also work if you want to use them.

Here is the actual code used behind the Topic 1 - First Item page (where the layout being rendered is the one above):

% render "templates/web/layouts/doc.html" do

Hello I'm item 1

% end