Development

HoneyTrap Development

Writing a New Topic

This page shows how to create a new topic for the HoneyTrap docs.

Before you begin

Create a fork of the HoneyTrap documentation repository as described in Creating a Documentation Pull Request.

Choosing a page type

As you prepare to write a new topic, think about which of these page types is the best fit for your content:

Task A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. .
Tutorial A tutorial page shows how to accomplish a goal that ties together several HoneyTrap features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the HoneyTrap features that are being tied togeter, but should link to related concept topics for deep explanations of individual features. A good example for this is the Getting Started page.
Concept A concept page explains some aspect of HoneyTrap. For example, a concept page might describe the HoneyTrap Listeners and explain the role it plays as part of the HoneyTrap Agent as it is configured, implemented, and tested. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see the What is HoneyTrap page.

Each page type has a template that you can use as you write your topic. Using templates helps ensure consistency among topics of a given type.

Choosing a title and filename

Choose a title that has the keywords you want search engines to find. Create a filename that uses the words in your title separated by hyphens. For example, the page Writing a new topic (this page) has filename write-new-topic.md. An example is shown below:

   http://docs.honeytrap.io/docs/home/contribute/write-new-topic/

Adding the topic title to the front matter

In your topic, put a title field in the front matter. The front matter is the YAML block that is between the triple-dashed lines at the top of the page. Here’s an example:

---
title: Installing HoneyTrap Agent
---

Choosing a directory

Depending on your page type, put your new file in a subdirectory of one of these:

You can put your file in an existing subdirectory, or you can create a new subdirectory.

Creating an entry in the table of contents

Depending page type, create an entry in one of these files:

Including code from another file

To include a code file in your topic, place the code file in the HoneyTrap documentation repository, preferably in the same directory as your topic file. In your topic file, use the include tag:

{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" ghlink="/<PATHFROMROOT>" %}

where:

Here’s an example of using the include tag:

{% include code.html language="yaml" file="sample-tut.yaml" ghlink="docs/tutorials/some-fancy-tutorial/sample-tut.yaml" %}

Adding images to a topic

Put image files in the /images directory. The preferred image format is SVG.

What’s next