diff options
| -rw-r--r-- | Makefile | 28 | ||||
| -rw-r--r-- | README.md | 10 | ||||
| -rwxr-xr-x | bin/mkdocs-prep.pl | 87 |
3 files changed, 109 insertions, 16 deletions
@@ -1,22 +1,18 @@ -# Depends: myrepos git mkdocs w3c-linkchecker libtext-hogan-perl +# Depends: myrepos git mkdocs w3c-linkchecker libconfig-tiny-perl libpath-tiny-perl libtext-hogan-perl libio-prompter-perl -include site.mk domain ?= example.org +eventhost ?= event.$(domain) shellhost ?= shell.$(domain) githost ?= source.$(domain) gitshellhost ?= $(shellhost) matrixhost ?= matrix.$(domain) organisation ?= Example orga contact_sysadmins ?= contact sysadmins +VARIABLES = domain eventhost shellhost githost gitshellhost matrixhost organisation contact_sysadmins -MUSTACHE = cat source/source/USE.md | perl -MText::Hogan::Compiler -0777 -nE '\ - my $$compiler = Text::Hogan::Compiler->new;\ - my $$template = $$compiler->compile($$_);\ - say $$template->render({ \ - domain => "$(domain)", shellhost => "$(shellhost)", githost => "$(githost)", gitshellhost => "$(gitshellhost)", \ - matrixhost => "$(matrixhost)", \ - organisation => "$(organisation)", contact_sysadmins => "$(contact_sysadmins)" })' +MKDOCS_PREP ?= bin/mkdocs-prep.pl all: doc @@ -30,23 +26,24 @@ check: docs: mkdir -p docs find docs -type l -delete - $(MUSTACHE) < README.md > docs/index.md - $(MUSTACHE) < SETUP.md > docs/setup.md + $(MKDOCS_PREP) README.md docs/index.md + $(MKDOCS_PREP) SETUP.md docs/setup.md docs/%: source mkdir -p docs/$* - $(MUSTACHE) < source/$(subst /,-,$*)/README.md > docs/$*/index.md + $(MKDOCS_PREP) source/$(subst /,-,$*)/README.md docs/$*/index.md $(if $(wildcard source/$(subst /,-,$*)/USE.md),\ - $(MUSTACHE) < source/$(subst /,-,$*)/USE.md > docs/$*/use.md) + $(MKDOCS_PREP) source/$(subst /,-,$*)/USE.md docs/$*/use.md) $(if $(wildcard source/$(subst /,-,$*)/ADMIN.md),\ - $(MUSTACHE) < source/$(subst /,-,$*)/ADMIN.md > docs/$*/admin.md) + $(MKDOCS_PREP) source/$(subst /,-,$*)/ADMIN.md docs/$*/admin.md) $(if $(wildcard source/$(subst /,-,$*)/SETUP.md),\ - $(MUSTACHE) < source/$(subst /,-,$*)/SETUP.md > docs/$*/setup.md) + $(MKDOCS_PREP) source/$(subst /,-,$*)/SETUP.md docs/$*/setup.md) $(if $(wildcard source/$(subst /,-,$*)/DEVELOP.md),\ - $(MUSTACHE) < source/$(subst /,-,$*)/DEVELOP.md > docs/$*/devel.md) + $(MKDOCS_PREP) source/$(subst /,-,$*)/DEVELOP.md docs/$*/devel.md) init: mr update + $(if $(wildcard site.mk),,$(foreach v,$(VARIABLES),echo $v = $($v) >> site.mk;)) clean: rm -rf site @@ -54,5 +51,6 @@ clean: distclean: clean rm -rf source + rm -f site.mk .PHONY: all doc check clean distclean @@ -1,3 +1,11 @@ # Documentation of system features _(features)_ -This is documentation of system features at {{organisation}}. +This is documentation for system features at Example orga. + + +## Special strings + +NB! This documentation uses special strings +which you may want to adapt for your local setup: + +organisation: Example orga diff --git a/bin/mkdocs-prep.pl b/bin/mkdocs-prep.pl new file mode 100755 index 0000000..7d9b1d3 --- /dev/null +++ b/bin/mkdocs-prep.pl @@ -0,0 +1,87 @@ +#!/usr/bin/perl + +use v5.18; # needed for \h (horizontal whitespace) in regexes +use strict; +use warnings; +use autodie; +use List::Util qw(pairs); +use Config::Tiny; +use Path::Tiny; +use Text::Hogan::Compiler; +use IO::Prompter; + +=head1 NAME + +mkdocs-prep - mkdocs preprocessor expanding inline hints and mustache tokens + +=head1 VERSION + +Version 0.02 + +=head1 SYNOPSIS + +=head1 DESCRIPTION + +B<mkdocs-prep> prepares a markdown document for B<mkdocs> processing. + +The document is converted using inline hint section to a mustache template +and resolved using an external set of single-word tokens. + +A document section named "Special strings" is parsed for token definitions +where each line lists a single-word token, a colon, and default string. +The section is then stripped, +and all occurences of default strings are replaced with tokens +wrapped with double curly brackets. + +Template tokens are gathered from external config file F<site.mk>, +where each line lists a token, an equals sign, and replacement string. + +Inline defined tokens not declared in F<site.mk> will be prompted for. +if a value is provided it will be used, and also saved in F<site.mk>. +If no value is provided then inline default string is used. + +Each token in the document, +wrapped with double curly brackets {{like_this}}, +is replaced (including brackets) with corresponding string. + +=cut + +my ( $infile, $outfile ) = @ARGV; +@ARGV = undef; + +my $cfgfile = path('site.mk'); +my $config = $cfgfile->exists + ? Config::Tiny->read( $cfgfile, 'utf8' ) + : Config::Tiny->new; +my $config_has_changed; + +my $content = path($infile)->slurp_utf8; + +$content =~ s/^#+\s*Special strings\s*\n((?:\n|[^#\n][^\n]*\n)*)//m; +my $section = $1 || ''; +my %defaults; +while ( $section =~ /^(\w+)\h*:\h*(\w\S*(?:\h+\S+)*)/mg ) { + my $token = $1; + my $string = $2; + + unless ( exists $config->{_}->{$1} ) { + $_ = prompt "Which string should replace token '$token'?"; + next unless length $_; + $config->{_}->{$1} = $_; + $config_has_changed++; + } + + $content =~ s/\Q$string\E/{{$token}}/g; +}; + + +my $compiler = Text::Hogan::Compiler->new; +my $template = $compiler->compile($content); + +path($outfile)->spew_utf8( $template->render( $config->{_} ) ); + +$cfgfile->touch; +$config->write( $cfgfile, 'utf8' ) + if $config_has_changed; + +1; |