A tool built around pandoc to convert a markdown gitit wiki to any other formats.
Mandatory
-
pandoc
-
pandoc-types >= 1.16
Because of binary incompatible change to its interfaces. See the common errors section below.
If not met it would break most pandoc filters' compilation.
-
plantuml
Required at runtime by
plantuml_filter.hs
. -
graphviz
For the
dot
command required at runtime bydot_filter.hs
.
Optional (but strongly recommanded)
-
nix
-
nixpkgs > revision
551296a
This tool was tested against a nixpkgs repository at revision
551296a
taken at date 2016/04/07. If this minimal requirement is met (implying proper nix installation), then all other prerequisites will be automatically installed by thenix-shell
calls documented below.
Please take a look at the detailed setup section for per platform steps to perform as prerequisites.
For the moment, only html output is supported.
$ git clone https://my/url/to/jrg_wiki_pandoc_converter
$ cd jrg_wiki_pandoc_converter
$ nix-shell
[nix-shell]$ ./run.sh
You should find the result under out_html
.
Alternatively, the following last two command can be combined as one:
$ nix-shell --run ./run.sh
Note the nix-shell
invocation. This is not strictly required, but it allows us to use the
nix package manager in order to bring into scope all of the required dependencies. If you
do not want to use nix, you can manually install all the required dependencies manually on
your system. Please look at ./shell.nix
for the complete listing.
The script also support optional parameters. Please look directly at ./run.sh
to
see what those are. By default, the html output format is selected, wiki_in
is
cloned inside this repo and the output ends up under ./out_html
.
The pandoc document conversion tools allows for custom filters. Those filters are located
in the ./filters
sub directory. The filter will be automatically compiled (depending on
the used filter language) by the run.sh
script.
Currently used filters are:
-
filters/adapt_local_page_link_filter.hs
: A pandoc filter that, depending on output format, transforms link target url without extensions (used as internal page link) to links with appropriate path extensions. This is currently useful for the html output format so that it is possible to navigate the result locally without any needs for a backend server.The filter also transform absolute local urls into relative path.
Note that if the documentation is meant to be consulted through a properly configured http server, the transformation may optionnally be dropped.
-
dot_filter.hs
: A pandoc filter that transform graphiz dot code block (with class.dot
) into an image by runingdot
cli tool. -
plantuml_filter.hs
: A pandoc filter that transform plantuml code block (with class.plantuml
) into an image by runing theplantuml
cli tool.
adapt_local_page_link_filter
: Tranform only when output format is html, or html5.- Filters for all other used gitit plugins: ditaa, diagrams, etc.
- Non default, better looking css for the html output?
- Support other output format (e.g.: mediawiki, dokuwiki, etc).
- Support other wiki urls as input.
This tool will sync a local copy of [wiki_out_html repository] with the latest [wiki_in repository]'s content.
The local copy is by default placed inside this repository at ./wiki_out_html
.
Note that the user still need to manually add file to git staging area, commit and push.
./sync_wiki_out_html.sh
ERROR: Could not find minimal
1.16
pandoc-types
library version required to buildpandoc
filters. Current version is ``
It means no pandoc-types
version is installed in the current environement.
You probably forgot to enter the nix-shell
environement before launching the run.sh
command.
ERROR: Could not find minimal
1.16
pandoc-types
library version required to buildpandoc
filters. Current version is1.15.4
.
It means the currently installed version of the haskell library pandoc-types
is not recent
enough to meet the requirements of the tool's pandoc filter. If the version was lower than
1.16
the pandoc filters would not compile. This is because 1.16
introduce binary incompatible
change in interfaces related with the addition of an attributes field to both Image
and
Link
constructors. See pandoc-types - changelog.
Please make sure your nixpkgs repository is up-to-date. We tested this tool against a nixpkgs
at revision 551296a
taken at date 2016/04/07. This revision came with a pandoc-types
library at version 1.16.1
.
Here is the minimal setup steps required assuming filters are prebuilt for you platform:
-
Install Git for windows.
-
Install pandoc.
-
Install graphviz
You should ensure the binaries for this package (e.g:
C:\Program Files (x86)\Graphviz2.38\bin
) are added toPATH
. -
Install jre.
-
Install plantuml.
The environement variable
PLANTUML_JAR
should point on the*.jar
file.
Additionnally, if the filters are not prebuilt for your platform or you mean to modify them, here's the supplementary setup steps to perform:
-
Install haskell-platform-full.
Installing the full version is important as it is non trivial to build the network package under windows.
-
From a Cmd shell, install the required haskell packages using cabal:
cabal update cabal install pandoc-types process-streaming pipes-transduce SHA utf8-string hslogger