Changelog: Improved Search, Callouts & Emoji

This is the first in a series of posts where we want to talk more publicly about the features we’re building and the decisions that went into making them a reality. Today, we’re talking about how we recently improved our search function, and added two small, but useful, additions we made to our custom flavor of Markdown: callouts and emojis.

Improved Search

The first version of our search was reasonably naive. We rely on PostgreSQL’s full-text search capabilities and used the websearch_to_tsquery function to parse the query sent by the user and find matches in the tsvector column describing the stored documents.

This was however quite limited in scope and often would fail to find what seemed like obvious matches. This is mainly due to websearch_to_tsquery not supporting prefix matches.

Now, we’ve added some custom functionality, and improved matching in general through a custom search query parser and compiler. We now parse the query into its constituent parts in order to apply specific WHERE clauses and to create a custom, improved tsquery string for PostgreSQL.

Let’s see it in action.

You can now use the new custom functions that allow you to match documents either by project or title. We also support the basics like prefix searches and quoted identifiers.

We plan to do a proper walkthrough of the technical details of how this works soon.

You can try this out in practice with our own docs.

Callouts

Callouts, sometimes call admonitions, are blocks that can be used to call attention to a particular piece of text. Maybe a notice, warning, or an alert. They are featured in many custom Markdown flavors and can be very useful in structuring your documentation.

Here’s an example from our own documentation.

They also come in different colors:

How do they work?

The syntax we ended up going with was the following:

1
2
3
4
5
6
7
{% info This is the title %}

This is the content. You can put anything here.

![even pictures](/my-cat.jpg)

{% end %}

The first line starts the callout and defines the type and optional title. The types are info, success, warning, and error, which generate blue, green, yellow, and red callouts respectively.

Emojis Shortcodes

The keen eyed reader may have noticed the above example had a lock emoji in the callout title. Accompanying the callout change is support for emoji shortcodes. You can now use GitHub-style emoji shortcodes in your docs and Doctave will render them into Unicode emojis.

These can be useful anywhere in documentation, but compose very nicely with callouts in their titles.

So now, if you write :bell: in your documentation, Doctave will render it as 🔔.

That’s all for now

These changes are available in our open source documentation generator from version 0.3.0, and of course on Doctave.com. Do let us know what you think!

We have some really exciting bigger features planned for Doctave and we will be posting about them in due time.

In the meantime, happy documenting!