Skip to content

A content management guide for non developers

Jump to bottom
Leszek Pietrzak edited this page Mar 11, 2022 · 4 revisions

This guide should help you with finding answers to these questions:

  1. How to create a support.kobotoolbox.org article?
  2. How to add an image or video to an article?

Prerequisites

Things you definitely need:

  1. A GitHub account.
  2. Your account has to be added to KoBo organization on GitHub by John or Tino (you need permission to edit files).

General notes

Never edit files inside _build/html directory, as these are automatically generated from markdown files.

All the changes you make (every time you "Commit changes") on GitHub are reversible!

After doing some changes, give GitHub a few minutes and then check out the live website if the changes are correct.

What is support.kobotoolbox.org?

Our support.kobotoolbox.org website is built with Sphinx - a python documentation generator. The built website is deployed with GitHub Pages.

Sphinx is a static documentation generator. It means that it takes text files (AKA "content") written in Markdown, and uses few configuration files to create a complex website. There is no database or admin panel. It also means that whenever you commit (AKA "save") changes to some files, the website will rebuild itself (can take up to few minutes, usually is faster).

Few pieces of information about our Sphinx configuration:

  • All articles are inside source/ directory.

  • For given article some_example.md we follow this directory structure:

    • source/images/some_example/ directory for images
    • source/_static/files/some_example directory for other files (videos, XLS forms, etc.)

  • The list of articles you see at the main support page (or in the sidebar of any article) is generated from source/index.rst file.
    • NOTE: when you create new article and don't add it to the list, it will be accessible by manually typing it's url.

  • Using files with spaces in name is illegal - please use _ (underscores).

Editing content

Editing articles

  1. Open project repository: github.com/kobotoolbox/docs.

  2. Find the page (i.e. the file) you want to edit. You can navigate by clicking through displayed files and directories.

    • PROTIP: there is a hidden search feature! While on the repository, press t and a search box will appear, where you can type a file name or path.

  3. You will see the content of the file. It will be Markdown code.

  4. Click "Edit this file" icon button (it's small, sorry).

  5. Make changes. Try to remember about the indentation (these are the space characters in front of each line), mimic other lines if in doubt.

    • PROTIP: if you will close the browser tab by mistake, your changes should be still there when you reopen the tab.

  6. Save by clicking "Commit changes".
    • NOTE: leave the default options.
    • PROTIP: you can add a short description of what your changes are in the "Commit changes" box above.

Creating articles

  1. Open project repository: github.com/kobotoolbox/docs.

  2. Find the source directory in which you want the file to be created. You can navigate by clicking through displayed files and directories.

  3. Click "Add file" icon button and choose "Create new file" option.

  4. Type the file name. Remember about the extension - hint: you want .md.
    • NOTE: best file name has only lowercase letters and _ character instead of spaces.

  5. Add the content of the page. The first lines of text should have # character followed by the title:

    # How to write content
    • NOTE: you can mimick the existing files to see what code you need.
    • NOTE: the # title is being displayed in the browser tab, when you open the page, or in sidebar list etc.

  6. Save by clicking "Commit new file".

    • NOTE: leave the default options.
    • PROTIP: you can add a short description of the new file in the "Commit new file" box above.

Completing these 6 steps makes the article available at support.kobotoolbox.org/some_example.html, but it will not appear in the sidebar menu just yet.

Adding article to list

  1. Open project repository: github.com/kobotoolbox/docs.

  2. Find the source/index.rst file. You can navigate by clicking through displayed files and directories.

  3. You will see the content of the file. It will be reStructuredText code.

  4. Click "Edit this file" icon button (it's small, sorry).

  5. Find a section in which you want the article to appear. Look for a line that starts with :caption:. You will find all existing articles mentioned a few lines below it.
    • NOTE: Try to remember about the indentation (these are the space characters in front of each line), mimic other lines if in doubt.

  6. Save by clicking "Commit changes".
    • NOTE: leave the default options.
    • PROTIP: you can add a short description of what your changes are in the "Commit changes" box above.

Deleting articles

  1. Open project repository: github.com/kobotoolbox/kobotoolbox.org.

  2. Find the file to be deleted. You can navigate by clicking through displayed files and directories.

    • PROTIP: there is a hidden search feature! While on the repository, press t and a search box will appear, where you can type a file name or path.

  3. Click "Delete this file" icon button (it's small, sorry).

  4. Confirm by clicking "Commit changes".

    • NOTE: leave the default options.
    • PROTIP: you can add a short description of why you are deleting the file in the "Commit changes" box above.

  5. Follow steps from "Adding article to list" to remove the deleted article from the list.

Specific content elements

Adding an image

  1. Have an article page some_name_here.md.
  2. Create new directory at source/images/some_name_here if such directory doesn't exist yet.
  3. Add your image file to source/images/some_name_here/FILENAME WITH EXTENSION.
  4. In your article write: ![image](/images/some_name_here/FILENAME WITH EXTENSION).

Adding a video

  1. Have an article page some_name_here.md.
  2. Create new directory at source/_static/files/some_name_here if such directory doesn't exist yet.
  3. Add your video file to source/_static/files/some_name_here/FILENAME WITH EXTENSION (mp4 is prefered).
  4. In your article write: <video controls><source src="./_static/files/some_name_here/FILENAME WITH EXTENSION" type="video/mp4"></video>. Note: if you use other format than mp4 you will need to update type= attribute accordingly.

Downloadable file link

  1. Have an article page some_name_here.md.
  2. Create new directory at source/_static/files/some_name_here if such directory doesn't exist yet.
  3. Add your file to source/_static/files/some_name_here/FILENAME WITH EXTENSION.
  4. In your article write: <a download href="./_static/files/some_name_here/FILENAME WITH EXTENSION">LINK TEXT</a>.

An icon from KPI interface

Note: the available icons are coming from the production version. There is no way to use the beta icons, sorry.

To use the icons, the simplest way is to:

  1. Open icons list from support.kobotoolbox.org
  2. Copy a snippet
  3. Paste into your article :)

If the icons list doesn't load up, the snippets code looks like this: <i class="k-icon k-icon-ICON_NAME_GOES_HERE"></i>, e.g.

<i class="k-icon k-icon-template"></i>

Multi element note

To add a "note" that works with any elements inside, please use <section class="note>, e.g.:

<section class="note">
    <h3>Test</h3>
    <p>One ore more paragraphs.</p>
    <p>One ore more paragraphs.</p>
</section>

It will produce a blue rounded border surrounding the content inside.

NOTE: Unfortunately you can't use markdown inside the <section>, please use only HTML tags.

Clone this wiki locally