author manual


A note before to start.

Below default and optional items are indicative by now. In this version of django-rstblog an optional field is set to its default value in case of load of a new article. Otherwise, i.e. changing an article already present in DB, an optional field is ignored, causing the previous value to survive.

If you wish to change an optional field value at article update, set it explicitly. How? Continue reading :-)

Well, end of note, let’s start the work.

This is the scene: you, the author, have availability of a working site that uses diango-rstblog to publish your articles. So, someone (a site master) gave you:

  • the URL of the site [7];
  • your username;
  • your password.

You’ll need them to upload the article: keep them safe and begin how to write an article, … keep going …

Article organization

Let’s speak how organize an article that we’ll publish using diango-rstblog.

It is written in a file with two parts. The first part is about fields categorizing our article. The second part stocks the content of the article.

The two parts are separated by a line containing the string:

.. hic sunt leones

Yes: two dots, space, and the phrase hic sunt leones. No more, no less, in a single line [1].

So, reiterating the concept, we have this schema:

fields area (generally: one field every line)
optional empty line
.. hic sunt leones
optional empty line
article contents

Hereafter, as example, we report first lines of an article about Marco Tullius Cicero, whose content is extracted from wikipedia. It’s written using reST:

:markup: restructuredtext
:language: en
:title: Speaking about Cicero
:created: 2018-08-05 10:00:00
:modified: 2018-08-05 10:00:00
:slug: speaking-about-cicero
:summary:  The Marcus Cicero's profile: informations and life.
:authors:   Wikipedia
:category: latin literature history

.. hic sunt leones

Speaking about Cicero

*Marcus Tullius Cicero* was a Roman statesman, orator, lawyer
and philosopher, who served as consul in the year 63 BC.
He came from a wealthy municipal family of the Roman equestrian
order, and is considered one of Rome's greatest orators
and prose stylists.


Article filename

Some speech about article file. How to name it? Our advice is: create a rule and follow it. So you’ll have a clearer working area.

As example, you can use a progressive number and a very short title note. So, these:

  • 159_full_text_search_python.rst
  • 160_full_text_search_python.en.rst

could be two files about an article regarding how to do full text search in python. First is in default language, the second is in English language.

But whatever rule you’ll adopt, it will be right: django-rstblog is filename agnostic. Just a caution: it would be better if file extension is related to the format used; i.e.: .md for markdown text, .rst for reST text and .html for html text.

Two warnings about filenames:

  • 1st: you cannot use the same filename to write two different articles; this is obvious: on your PC, if you try to save a new article using a used filename, you’ll scratch the old article;
  • 2nd: you cannot change filename to an article already uploaded; this is less obvious, but trust me: it is true; if you need to change filename to an old article, you must tell it to the site master: he knows how to do it.

Now we’ll speak in more detail about fields and content areas.

Article fields (aka: attributes)

As we saw, fields categorize our article. So they are vital.

django-rstblog uses fields shown in previous example article about Marco Tullius Cicero. There is one more, but we’ll talk about it in a while.

By now, we exhort you to use all the fields shown in the example and to pay attention to typos. At this early stage of development (v0.1 as we write) there aren’t a lot of controls about syntax errors.

A single field has structure:

:fieldname: fieldvalue

django-rstblog decides fieldname(s). So you must use the right fieldname without typos. Instead what to put in fieldvalue is up to you.

Let’s see the single fields meaning.


This specify what markup language you use to write article content. Note the phrase article content. In fact field area is ever written using reST syntax.

Acceptable values for this field are: markdown, restructuredtext [2], html.

Optional: no.


:markup: restructuredtext


This is about what language you use to write the article content.

Acceptable values are defined from your site configuration. And it’s the site master responsability to configure it. Probably, at least english (written as en) would be available. Languages are invoked using their abbreviations; i.e. it for italian, fr for french, es for spanish, and so on.

Optional: no.


:language: it


This is the article title. It is shown in the blog index to identify your article and as a link to read it.

Acceptable values: whatever you want, provided that there are no other articles with the same title in the blog. Article title must be unique in the site. The maximum length is 250 characters.

Optional: no.


:title: Speaking about Cicero

created and modified

These are two fields showing:

  • the first the article creation date and time;
  • and the second the article last modified date and time.

Acceptable values. Whatever, in the format: YYYY-MM-DD HH:MM:SS

Optional: yes.

Default value: current date.


:created: 2018-08-05 10:00:00
:modified: 2018-08-05 10:00:00


Slug is the last piece of information used in the URL to reach your article. Usually it reflects the article title to help the reader (and the web crawler programs) to remember the article title.

Acceptable values. As titles, even slugs must be unique in the blog. Futhermore, they must be composed of a subset of ansi characters. To stay smooth, it’s usual to use only lowercase regular letters, with puntuation marks and spaces substitued by dashes. Maximum length is 250 characters.

Optional: no.

Example. If your article would be reached by this url:, you’ll use:

:slug: speaking-about-cicero


This field value summarizes your article content. It is shown in the blog index page after the title of article.

Accepted values. No restrictions here. And this field can accept even multiple lines contents. If you want to use multiple lines, you need to indent it from the second line on.

Optional: yes.

Default: the empty string.

Example of multiple lines summary:

summary:The Marcus Cicero’s profile: informations and life. From wikipedia in english language.


Put here the name(s) of author(s) of the article (your name, I suppose :-). In case of multiple authors, keep them in one line and separate them using a comma (,).

Accepted values. Author name must be present in blog database. It is responsability of site manager to insert the names of accepted authors.

Optional: yes.

Default: null.


authors:Lawrence of Arabia


This is the master of categorizations. It catalogs our article assigning it to a main type.

Accepted values. Again, it depends on the configuration of your blog. It is responsability of site manager to insert the accepted categories in the blog database. And only values present in this database are accepted by rstblog.

Optional: no.


:category: latin literature history


What to say about content?

Here the author develops his true work: to write the articles contents.

You are free to choose the format type you like throught markdown, reST and html.

Mathematical expressions

In case you need to write mathematical expressions, it’s simpler to use Markdown as markup language. At the moment, django-rstblog is configured to render math to html from Markdown.

Loading the article content

A last note. When you would publish your work, you need to call:

django-rstblog will ask you for your username and password. When you’ll give them to it, it will ask for the article filename to load. Here you can browse to the article file [3] and submit it, loading the request file.

Advanced attributes

Hereafter more fields, useful in case of more advanced functions.


Surprise: a field name not quoted in the article about Marco Tullius Cicero! What is this? You can send to django-rstblog even articles that are translations of article already known by rstblog. If is this the case, in this field you write the title of the original (translated) article.

If this field is missing, the article is an original article, meaning it is a principal article whatever its language.

Accepted values. A title of an article present in the blog database.

Default value: Null [4].

Optional: yes.

Example. If you write a translation of article about Marco Tullius Cicero, it could be as follow:

:markup: restructuredtext
:language: it
:title: Parlando di Cicerone
:created: 2018-08-05 10:00:00
:modified: 2018-08-05 10:00:00
:slug: parlando-di-cicerone
:summary:  Il profilo di Marco Tullio Cicerone: notizie e vita.
:authors:   Wikipedia
:category: latin literature history
:translation_of: Speaking about Cicero

.. hic sunt leones

Parlando di Cicerone

*Marco Tullio Cicerone* è stato uno statista Romano, oratore, avvocato
e filosofo, che ha servito come console nell'anno 63 AC.
Veniva da una agiata famiglia cittadina dell'ordine Romano degli Equestri,
ed è considerato uno dei più grandi oratori e scrittori di Roma.


As you can see, in the fields area of this translation, we changed:

  • the language indicator, to reflect the new language used in the translation;
  • the title (remember: two equal titles aren’t possible in the same blog);
  • the slug (like above: no equal slugs in the blog, and we would match as near possible the title);
  • the summary (maybe it would be read from Italians …).

And we added:

  • the translation_of field, with a value of Speaking about Cicero, the title of translated article.


This is about considering published, or not, the article. Usually django-rstblog regards an article as published by default, unless the article author sets this filed to no [5]. An unpublished article:

  • doesn’t compare in indexes;
  • doesn’t compare in sitemap.xml;
  • isn’t shown, even if you request it using directly the correct slug in URL.

But it’s counted in statistics.

Accepted values: yes or no.

Default value: yes.

Optional: yes.


:published: yes


offer_home is about to show the article in the blog home index.

django-rstblog shows in its home some, usually 20 [6], newer articles, checking their creation dates.

If you if you want an article not to be counted between the articles to consider in home, you can set this field to no.

Accepted values: yes or no.

Default value: yes.

Optional: yes.


:offer_home: yes


If you load an image in contents/media/images, using this field you can link it from the summary in home page. In practice, you an use an image to characterize the article. A kind of visual tag.

Moreover, you can show this image in the main window of the article. You can control this behaviour using the next field: image_in_content.

Accepted values: the image filename as a string.

Default value: no.

Optional: yes.


:image: django-logo-negative.svg


If you indicate an image as an article characterizer, it is ever showed in the index page. And it is possible to show it even in the window of the article content.

This is the default behavior. If you wish, you can avoid to show this image in the window of the article content, setting to no the field image_in_content.

This is desiderable if you have an article showing the same image in its contents. In such a case django-rstblog would show this image twice. Not a beautiful behavior.

Accepted values: yes or no.

Default value: yes.

Optional: yes.


:image_in_content: no

Author manual end

That’s all folk about author manual. Thank you to read it. We hope you enjoy it.

[1]A point to rember. If you wish, this signal could be changed by the site manager. And an anecdote. People say that this phrase was used in the maps of ancient Rome, to indicate unexplored territories of Africa. But there is no firm evidence that this is true. In this context we adopt it to indicate that from here on we enter the unknown meanders of the creation of the article.
[2]Note the use of the full name of the sintax type.
[3]Or directly type it, if you remember its full path and name.
[4]Meaning: it is missing.
[5]The no value is meaning. django-rstblog interprets any other value as yes.
[6]This value could be modified, but it is an operation to do during the application installation.
[7]The site URL will be something of the type: https://site-domain/blog.