X-Git-Url: http://git.wpitchoune.net/gitweb/?p=www.git;a=blobdiff_plain;f=src%2Fnews%2Fasciidoctor_to_rss.adoc;h=a5291dc14378d2ce5f95ac6856a5d25e3a21897c;hp=8fc823367f285408441c4c448fe88d7a3a88ee84;hb=100fa8ff715a4431da75c3225e1c79db9fa6ed16;hpb=3e957c3742892aeb9c7bd248bc074e73512fef6c diff --git a/src/news/asciidoctor_to_rss.adoc b/src/news/asciidoctor_to_rss.adoc index 8fc8233..a5291dc 100644 --- a/src/news/asciidoctor_to_rss.adoc +++ b/src/news/asciidoctor_to_rss.adoc @@ -3,18 +3,21 @@ Jean-Philippe Orsini :date: 2016-11-07 :icons: font -In order to have a website based only on Asciidoctor -documents, I have written a small utility which -converts a set of Asciidoctor documents to HTML pages and -generates a RSS 2.0 feed. +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: -* maven +* http://maven.apache.org/download.cgi[Apache Maven] (3.3.9) -* java (>1.7) +* http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] (Sun JDK >=1.8) The sources can be retrieved from GIT: @@ -31,22 +34,72 @@ mvn clean install == Howto write news -Each news has to be written in a separate Asciidoctor document +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 +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. -You can see some 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 +Here is an example of _news_: + +[source, asciidoc] +---- += Asciidoctor to RSS +Jean-Philippe Orsini +: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 of the utility can be done in text file. +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. -See an example at https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/asciidoctorrss.props;hb=HEAD . +`html.header.file`: the content of the denoted file will be added in the `head` block of +the generated HTML documents. == Run the utility @@ -58,14 +111,15 @@ asciidoctor_to_rss.sh `IN_DIR`: the directory containing the news as Asciidoctor documents. -`OUT_DIR`: the output directory which contains all generated files +`OUT_DIR`: the output directory which contains all generated files. -`CFG_FILE`: the path to the configuration file +`CFG_FILE`: the path to the configuration file. The `OUT_DIR` will contain: -* one HTML file for each Asciidoctor document +* one HTML file for each Asciidoctor document, -* the `news.html` file +* the https://wpitchoune.net/news/news.html[`news.html`] file, -* the `feed.xml` file which is a feed compatible with RSS v2.0. +* and the https://wpitchoune.net/news/news.html[`feed.xml`] file which is a feed + compatible with RSS v2.0.