author manual table of contents
Note
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:
You’ll need them to upload the article: keep them safe and begin how to write an article, … keep going …
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 leonesoptional empty linearticle 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.
...
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:
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:
Now we’ll speak in more detail about fields and content areas.
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.
Example:
: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.
Example:
: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.
Example:
:title: Speaking about Cicero
These are two fields showing:
Acceptable values. Whatever, in the format:
YYYY-MM-DD HH:MM:SS
Optional: yes.
Default value: current date.
Example:
: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:
https://my.blog.org/blog/show/speaking-about-cicero, 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.
Example:
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.
Example:
: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.
Let us to give you some advices about other files you could refer from your article.
First of all: the external hyperlinks. These are html pages available thanks to other sites. And all three quoted formats allow to refer them. As an example, this is an external hyperlink to wikipedia main page using reST:
`wikipedia <https://en.wikipedia.org/wiki/Main_Page>`_
It shows word wikipedia and it jumps to its main page if you click
on the word.
Then, what about hyperlink to other article in the site? In this case,
use the (relative) article URL. Remember: it uses /blog/show as prefix,
and slug as article identifier. So to hyperlink to your article
Speaking about Cicero you can use (for example):
...
you can read our wonderful `article about Cicero </blog/show/speaking-about-cicero>`_
...
Note that it isn’t necessary to report the site domain (my.blog.org), and
we use the article slug.
And, last but not least, how hyperlink to other files (not articles) present in our site? Here we need some technical clarifications to keep in touch.
In our site, files that aren’t articles can live on these directories:
pages that hosts the site pages that aren’t articles;media that hosts other type of files, such as images,
audio, video, pdf, and so on.Usually media has one subdirectory for every kind of hosted file. I.e.:
media/images to keep images;media/pdfs to store pdf files, and so on.As you can argue, if you would hyperlink to mylife.pdf file, you can
use:
...
`here </media/pdfs/mylife.pdf>`_ you can know something more about my life.
...
By now, these files must be uploaded to your site using some other kind of
software; maybe ftp, or remote copy. This means that you must be
a true site administrator to handle this files. If this is a problem
for you: stay tuned … In the future it’s
possible django-rstblog could upload even these files with the article.
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.
A last note. When you would publish your work, you need to call:
https://my.blog.org/blog/load-article
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.
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:
And we added:
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:
But it’s counted in statistics.
Accepted values: yes or no.
Default value: yes.
Optional: yes.
Example:
: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.
Example:
: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.
Example:
: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.
Example:
:image_in_content: no
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. |