= Asciidoctor to RSS
Jean-Philippe Orsini <jeanfi@gmail.com>
:date: 2016-11-07
:icons: font

In order to ease the edition of this website and
the management of the server, I want it to be purely
static and generated from http://asciidoctor.org[Asciidoctor] documents.

The _news_ part of the website is also written as Asciidoctor
documents, `asciidoctor_to_rss` is converting them into static
HTML pages and generates a RSS 2.0 file.

== Installation of asciidoctor_to_rss

It is required to install:

* http://maven.apache.org/download.cgi[Apache Maven] (3.3.9)

* http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] (Sun JDK >=1.8)

The sources can be retrieved from GIT:

----
git clone git clone https://git.wpitchoune.net/asciidoctor_to_rss.git
----

Compilation:

----
cd asciidoctor_to_rss
mvn clean install
----

== Howto write news

Each _news_ must be written in an http://asciidoctor.org[Asciidoctor] document
and all documents must be dropped into a directory.

There is not any restriction concerning the syntax because
the utility is based on the Java bridge of Asciidoctor.
I have added an attribute `date` which allows the utility
to know the publication date of the news.

Here is an example of _news_:

[source, asciidoc]
----
= Asciidoctor to RSS
Jean-Philippe Orsini <jeanfi@gmail.com>
:date: 2016-11-07
:icons: font

In order to ease the edition of this website and
the management of the server, I want it to be purely
static and generated from http://asciidoctor.org[Asciidoctor] documents.

The _news_ part of the website is also written as Asciidoctor
documents, `asciidoctor_to_rss` is converting them into static
HTML pages and generates a RSS 2.0 file.

== Installation of asciidoctor_to_rss

It is required to install:

* http://maven.apache.org/download.cgi[Apache Maven] (3.3.9)

* http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] (Sun JDK >=1.8)
----

You can see few examples at
https://wpitchoune.net/gitweb/?p=www.git;a=tree;f=src/news;hb=HEAD.
The source document of this _news_ is at
https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/news/asciidoctor_to_rss.adoc;hb=HEAD.

== Configuration

The configuration file of `asciidoctor_to_rss` is text file containing key/value pairs.

See an example at
https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/asciidoctorrss.props;hb=HEAD .

[source, text]
----
feed.title=News
feed.description=News of the wpitchoune.net website.
feed.link=https://wpitchoune.net/news/feed.xml
feed.baseurl=https://wpitchoune.net/news

html.header.file=src/header.html
----

`feed.title`: the title used for the feed, in the RSS 2.0 and `news.html` files.

`feed.description`: the description used in the RSS 2.0 file.

`feed.link`: URI of the RSS 2.0 file.

`feed.baseurl`: base URI where the HTML news files will be located.

`html.header.file`: the content of the denoted file will be added in the `head` block of
the generated HTML documents.

== Run the utility

The command line usage is:

----
asciidoctor_to_rss.sh <IN_DIR> <OUT_DIR> <CFG_FILE>
----

`IN_DIR`: the directory containing the news as Asciidoctor documents.

`OUT_DIR`: the output directory which contains all generated files.

`CFG_FILE`: the path to the configuration file.

The `OUT_DIR` will contain:

* one HTML file for each Asciidoctor document,

* the https://wpitchoune.net/news/news.html[`news.html`] file,

* and the https://wpitchoune.net/news/news.html[`feed.xml`] file which is a feed
  compatible with RSS v2.0.
