src/news/asciidoctor_to_rss.adoc

   1 = Asciidoctor to RSS
   2 Jean-Philippe Orsini <jeanfi@gmail.com>
   3 :date: 2016-11-07
   4 :icons: font
   5
   6 In order to ease the edition of this website and
   7 the management of the server, I want it to be purely
   8 static and generated from http://asciidoctor.org[Asciidoctor] documents.
   9
  10 The _news_ part of the website is also written as Asciidoctor
  11 documents, `asciidoctor_to_rss` is converting them into static
  12 HTML pages and generates a RSS 2.0 file.
  13
  14 == Installation of asciidoctor_to_rss
  15
  16 It is required to install:
  17
  18 * http://maven.apache.org/download.cgi[Apache Maven] (3.3.9)
  19
  20 * http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] (Sun JDK >=1.8)
  21
  22 The sources can be retrieved from GIT:
  23
  24 ----
  25 git clone git clone https://git.wpitchoune.net/asciidoctor_to_rss.git
  26 ----
  27
  28 Compilation:
  29
  30 ----
  31 cd asciidoctor_to_rss
  32 mvn clean install
  33 ----
  34
  35 == Howto write news
  36
  37 Each _news_ must be written in an http://asciidoctor.org[Asciidoctor] document
  38 and all documents must be dropped into a directory.
  39
  40 There is not any restriction concerning the syntax because
  41 the utility is based on the Java bridge of Asciidoctor.
  42 I have added an attribute `date` which allows the utility
  43 to know the publication date of the news.
  44
  45 Here is an example of _news_:
  46
  47 [source, asciidoc]
  48 ----
  49 = Asciidoctor to RSS
  50 Jean-Philippe Orsini <jeanfi@gmail.com>
  51 :date: 2016-11-07
  52 :icons: font
  53
  54 In order to ease the edition of this website and
  55 the management of the server, I want it to be purely
  56 static and generated from http://asciidoctor.org[Asciidoctor] documents.
  57
  58 The _news_ part of the website is also written as Asciidoctor
  59 documents, `asciidoctor_to_rss` is converting them into static
  60 HTML pages and generates a RSS 2.0 file.
  61
  62 == Installation of asciidoctor_to_rss
  63
  64 It is required to install:
  65
  66 * http://maven.apache.org/download.cgi[Apache Maven] (3.3.9)
  67
  68 * http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] (Sun JDK >=1.8)
  69 ----
  70
  71 You can see few examples at
  72 https://wpitchoune.net/gitweb/?p=www.git;a=tree;f=src/news;hb=HEAD.
  73 The source document of this _news_ is at
  74 https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/news/asciidoctor_to_rss.adoc;hb=HEAD.
  75
  76 == Configuration
  77
  78 The configuration file of `asciidoctor_to_rss` is text file containing key/value pairs.
  79
  80 See an example at
  81 https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/asciidoctorrss.props;hb=HEAD .
  82
  83 [source, text]
  84 ----
  85 feed.title=News
  86 feed.description=News of the wpitchoune.net website.
  87 feed.link=https://wpitchoune.net/news/feed.xml
  88 feed.baseurl=https://wpitchoune.net/news
  89
  90 html.header.file=src/header.html
  91 ----
  92
  93 `feed.title`: the title used for the feed, in the RSS 2.0 and `news.html` files.
  94
  95 `feed.description`: the description used in the RSS 2.0 file.
  96
  97 `feed.link`: URI of the RSS 2.0 file.
  98
  99 `feed.baseurl`: base URI where the HTML news files will be located.
 100
 101 `html.header.file`: the content of the denoted file will be added in the `head` block of
 102 the generated HTML documents.
 103
 104 == Run the utility
 105
 106 The command line usage is:
 107
 108 ----
 109 asciidoctor_to_rss.sh <IN_DIR> <OUT_DIR> <CFG_FILE>
 110 ----
 111
 112 `IN_DIR`: the directory containing the news as Asciidoctor documents.
 113
 114 `OUT_DIR`: the output directory which contains all generated files.
 115
 116 `CFG_FILE`: the path to the configuration file.
 117
 118 The `OUT_DIR` will contain:
 119
 120 * one HTML file for each Asciidoctor document,
 121
 122 * the https://wpitchoune.net/news/news.html[`news.html`] file,
 123
 124 * and the https://wpitchoune.net/news/news.html[`feed.xml`] file which is a feed
 125   compatible with RSS v2.0.