From de334a9e32d0d1d19c4aa98415cfe35866686157 Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Sun, 21 Feb 2016 14:31:05 +0100 Subject: man: improved content-parser docs --- man/blogc-source.7.ronn | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'man') diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn index 7fa0796..5a0a485 100644 --- a/man/blogc-source.7.ronn +++ b/man/blogc-source.7.ronn @@ -209,12 +209,22 @@ Links are defined using the following syntax: To learn more about blogc, [click here](https://blogc.rgm.io). +Whitespace characters and new lines are allowed between link text and link URL: + + To learn more about blogc, [click here] + (https://blogc.rgm.io). + ### Image Links Links can be combined with images: [![This is the image alt text](picture.jpg)](https://blogc.rgm.io) +Whitespace characters and new lines are allowed between alt text and image URL: + + [![This is the image alt text] + (picture.jpg)](https://blogc.rgm.io) + ### Automatic Links Automatic link is defined with 2 '[' before and 2 ']' after the URL. -- cgit v1.2.3-18-g5258 From 437ea5b71f7a1f6cd5d09b28259a8e49acab7fbc Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Sun, 21 Feb 2016 16:43:31 +0100 Subject: man: tests: minor documentation fix and more test coverage --- man/blogc-source.7.ronn | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'man') diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn index 5a0a485..c2c0490 100644 --- a/man/blogc-source.7.ronn +++ b/man/blogc-source.7.ronn @@ -203,6 +203,11 @@ Images are defined using the following syntax: This is an image: ![This is the image alt text](picture.jpg) +Whitespace characters and new lines are allowed between alt text and image URL: + + This is an image: ![This is the image alt text] + (picture.jpg) + ### Links Links are defined using the following syntax: @@ -220,10 +225,12 @@ Links can be combined with images: [![This is the image alt text](picture.jpg)](https://blogc.rgm.io) -Whitespace characters and new lines are allowed between alt text and image URL: +Whitespace characters and new lines are allowed between link text and link URL, +and between alt text and image URL: [![This is the image alt text] - (picture.jpg)](https://blogc.rgm.io) + (picture.jpg)] + (https://blogc.rgm.io) ### Automatic Links -- cgit v1.2.3-18-g5258 From 4c3533500058efaa2cabbe08f70e0b0a64ea3e37 Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Sat, 5 Mar 2016 19:46:52 +0100 Subject: man: added em/en-dashes --- man/blogc-source.7.ronn | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'man') diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn index c2c0490..c49f3ce 100644 --- a/man/blogc-source.7.ronn +++ b/man/blogc-source.7.ronn @@ -243,6 +243,11 @@ Automatic link is defined with 2 '[' before and 2 ']' after the URL. Line breaks can be added after a paragraph line adding 2 or more white spaces to the end of the line. +### En dashes and Em dashes + +Sequences of 2 '-' characters are converted to an En dash HTML entity. +Sequences of 3 '-' characters are converted to an Em dash HTML entity. + ## BUGS -- cgit v1.2.3-18-g5258 From ca6fb024c9632b73713432e30fce978a99f42213 Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Fri, 29 Apr 2016 00:57:10 +0200 Subject: man: added man page for blogc-git-receiver --- man/blogc-git-receiver.1.ronn | 126 ++++++++++++++++++++++++++++++++++++++++++ man/index.txt | 16 ++++-- 2 files changed, 136 insertions(+), 6 deletions(-) create mode 100644 man/blogc-git-receiver.1.ronn (limited to 'man') diff --git a/man/blogc-git-receiver.1.ronn b/man/blogc-git-receiver.1.ronn new file mode 100644 index 0000000..4eadece --- /dev/null +++ b/man/blogc-git-receiver.1.ronn @@ -0,0 +1,126 @@ +blogc-git-receiver(1) -- A simple login shell/git hook to deploy blogc websites +=============================================================================== + +## SYNOPSIS + +chsh -s $(command -v `blogc-git-receiver`) + +## DESCRIPTION + +**blogc-git-receiver** provides a PaaS-like way to deploy blogc(1) websites. +When used as a login shell, it will accept git payloads, creating bare repositories +as needed, and installing a hook, that will take care of rebuilding the website each +time someone push something to the `master` branch. + +The git repository must provide a `Makefile` (or a `GNUMakefile`), that should +accept the `OUTPUT_DIR` variable, and install built files in the directory pointed +by this variable. + +`blogc-git-receiver` is part of `blogc` project, but isn't tied to blogc(1). Any +repository with `Makefile` that builds content and install it to `OUTPUT_DIR` +should works with `blogc-git-receiver`. + +## SETUP + +After creating an user (`blogc` for the examples), change its shell to +blogc-git-receiver(1): + + # chsh -s $(command -v blogc-git-receiver) blogc + +Now add ssh keys to `/home/blogc/.ssh/authorized_keys`. Every key in +`authorized_keys` will be allowed to push to the git repositories, and even +create new ones. + +Also, make sure to install all the dependencies required by the websites, +including a web server. `blogc-git-receiver` can't handle web server virtual hosts. + +To deploy a website (e.g. blogc example repository): + + $ git clone https://github.com/blogc/blogc-example.git + $ cd blogc-example + $ git remote add blogc blogc@${SERVER_IP}:blogs/blogc-example.git + $ git push blogc master + +This will deploy the example to the server, creating a symlink to the built content +in `/home/blogc/repos/blogs/blogc-example.git/htdocs`. This symlink should be used +as the document root for the web server virtual host. + +### Setup with SELinux enabled (Fedora) + +Supposing the usage of nginx as webserver, running as the `nginx` user: + + # dnf install -y nginx policycoreutils-python-utils + # useradd -m -s $(command -v blogc-git-receiver) blogc + # gpasswd -a nginx blogc + # chmod -R g+rx /home/blogc + # su -c "mkdir /home/blogc/{builds,repos}" -s /bin/sh blogc + # semanage fcontext -a -t httpd_sys_content_t "/home/blogc/(builds|repos)(/.*)?" + # restorecon -R -v /home/blogc + # systemctl restart nginx + +After running these commands, the machine is ready to be used. + +## REPOSITORY MIRRORING + +Users can rely on `blogc-git-receiver` to mirror repositories to a remote Git +repository (e.g. a free Bitbucket private repository). This feature just requires +adding a remote called `mirror` to the bare repository in the server. If such remote +exists, `blogc-git-receiver` will `git push --mirror` to it. + +Please note that the `blogc` user must be able to push to the remote repository, and +that any content manually pushed to the remote repository is overwritten by +`blogc-git-receiver`. + +Some reasonable ways to allow the `blogc` user to push to the remote repository are: + +- Create a password-less SSH key. The key *must* be password-less, because the push + is automatic, and remote git hooks can't be interactive. +- Create an oauth token in the hosting service (if it supports oauth authentication + in git, e.g. GitHub) and add it to the git URL. + +The mirroring feature wont't block a `git push`, it will just raise warnings. That +means that if an error happens when mirroring the repository, the deploy will still +succeed. Users should pay attention to the git hook logs, to avoid losing data +due to repositories not being mirrored. + +To add the `mirror` remote: + + # su -s /bin/bash - blogc + $ git remote add --mirror=push mirror $YOUR_GIT_MIRROR_URL + +### Caveats of repository mirroring with SSH + +The authentication must be done with a password-less SSH key created by the `blogc` +user. + +As the `git push --mirror` call is automated, users must disable SSH strict host +checking in SSH's `~/.ssh/config` file: + + Host bitbucket.org + StrictHostKeyChecking no + +The example uses `bitbucket.org` as remote host, that should be changed if needed. + +To change this file, users must login with `/bin/bash` or any other "real" shell, +as `root`: + + # su -s /bin/bash - blogc + +## ENVIRONMENT VARIABLES + +`blogc-git-receiver` will export an environment variable called `BLOGC_GIT_RECEIVER` +when calling `gmake` to build websites. This variable can be used to enable building +of content that should only be built when running in production environment, for +example. + +## BUGS + +Please report any issues to: + +## AUTHOR + +Rafael G. Martins <> + +## SEE ALSO + +blogc(1), git(7), chsh(1), su(1), make(1) diff --git a/man/index.txt b/man/index.txt index a85e2a0..7f78f2a 100644 --- a/man/index.txt +++ b/man/index.txt @@ -1,9 +1,13 @@ # manuals -blogc(1) blogc.1.ronn -blogc-source(7) blogc-source.7.ronn -blogc-template(7) blogc-template.7.ronn +blogc(1) blogc.1.ronn +blogc-git-receiver(1) blogc-git-receiver.1.ronn +blogc-source(7) blogc-source.7.ronn +blogc-template(7) blogc-template.7.ronn # external manuals -make(1) http://man.cx/make(1) -strcmp(3) http://man.cx/strcmp(3) -strptime(3) http://man.cx/strptime(3) +make(1) http://man.cx/make(1) +chsh(1) http://man.cx/chsh(1) +su(1) http://man.cx/su(1) +strcmp(3) http://man.cx/strcmp(3) +strptime(3) http://man.cx/strptime(3) +git(7) http://man.cx/git(7) -- cgit v1.2.3-18-g5258 From d4003fcfc88df94831cb4a20e890816954f64129 Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Fri, 29 Apr 2016 01:17:38 +0200 Subject: man: added man page for blogc-runserver --- man/blogc-git-receiver.1.ronn | 2 +- man/blogc-runserver.1.ronn | 48 +++++++++++++++++++++++++++++++++++++++++++ man/index.txt | 1 + 3 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 man/blogc-runserver.1.ronn (limited to 'man') diff --git a/man/blogc-git-receiver.1.ronn b/man/blogc-git-receiver.1.ronn index 4eadece..e26ed09 100644 --- a/man/blogc-git-receiver.1.ronn +++ b/man/blogc-git-receiver.1.ronn @@ -1,4 +1,4 @@ -blogc-git-receiver(1) -- A simple login shell/git hook to deploy blogc websites +blogc-git-receiver(1) -- a simple login shell/git hook to deploy blogc websites =============================================================================== ## SYNOPSIS diff --git a/man/blogc-runserver.1.ronn b/man/blogc-runserver.1.ronn new file mode 100644 index 0000000..a306fbe --- /dev/null +++ b/man/blogc-runserver.1.ronn @@ -0,0 +1,48 @@ +blogc-runserver(1) -- a simple HTTP server to test blogc websites +================================================================= + +## SYNOPSIS + +`blogc-runserver` [`-t` ] [`-p` ]
+`blogc-runserver` [`-h`|`-v`] + +## DESCRIPTION + +**blogc-runserver** is a simple HTTP server that makes it easy to test blogc websites. +Users just need to point it to the directory where the target files where built. It +comes with a few pre-defined rules, similar to production webservers, that allow users +to quickly test their websites without configuring a webserver. + +`blogc-runserver` is part of `blogc` project, but isn't tied to blogc(1). It may be +able to serve any website built by static site generators. + +## OPTIONS + + * `-t` : + HTTP server listen address, defaults to `127.0.0.1`. + + * `-p` : + HTTP server listen port, defaults to `8080`. + + * `-v`: + Show program name, version and exit. + + * `-h`: + Show help message and exit. + +## ARGUMENTS + + * : + HTTP server document root. + +## BUGS + +Please report any issues to: + +## AUTHOR + +Rafael G. Martins <> + +## SEE ALSO + +blogc(1) diff --git a/man/index.txt b/man/index.txt index 7f78f2a..40a80d6 100644 --- a/man/index.txt +++ b/man/index.txt @@ -1,6 +1,7 @@ # manuals blogc(1) blogc.1.ronn blogc-git-receiver(1) blogc-git-receiver.1.ronn +blogc-runserver(1) blogc-runserver.1.ronn blogc-source(7) blogc-source.7.ronn blogc-template(7) blogc-template.7.ronn -- cgit v1.2.3-18-g5258 From 114b36f95116f62bfcf9d79e441ab81aed35454b Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Sat, 30 Apr 2016 02:41:00 +0200 Subject: man: added blogc-pagination(7) --- man/blogc-pagination.7.ronn | 122 ++++++++++++++++++++++++++++++++++++++++++++ man/blogc-source.7.ronn | 4 ++ man/blogc.1.ronn | 4 +- man/index.txt | 1 + 4 files changed, 129 insertions(+), 2 deletions(-) create mode 100644 man/blogc-pagination.7.ronn (limited to 'man') diff --git a/man/blogc-pagination.7.ronn b/man/blogc-pagination.7.ronn new file mode 100644 index 0000000..db40334 --- /dev/null +++ b/man/blogc-pagination.7.ronn @@ -0,0 +1,122 @@ +blogc-pagination(7) -- blogc's pagination support +================================================= + +## DESCRIPTION + +blogc(1) supports some basic pagination and post filtering, when running on +`listing` mode. Files are listed in the order that they are provided to +blogc(1) in the command line, no sorting is done. + +## PAGINATION PARAMETERS + +blogc(1) accepts some variables as `-D` options, that are used to filter the +files passed as arguments to it: + + * `FILTER_PER_PAGE`: + Integer, limits the maximum number of files to be listed. + + * `FILTER_PAGE`: + Integer, current page. If calling blogc(1) with 10 files, + `FILTER_PER_PAGE`=4 and `FILTER_PAGE`=3, it will return just the 2 last + files, skipping the first 2 pages with 4 files each one. + + * `FILTER_TAG`: + String, if defined, blogc(1) will only list files that declare a `TAGS` + variable, as a space-separated list of tags (tags can't have spaces, + obviously). See blogc-source(7) for details about how to define source + variables. The pagination filters will only act on the files with the + provided tag, instead of filtering the whole file set. + +## TEMPLATE VARIABLES + +blogc(1) will export some global blogc-template(7) variables, that can be used +to build links for next and previous page. + + * `CURRENT_PAGE`: + Integer, usually the same value of `FILTER_PAGE` pagination paramenter, if + defined, or 1. + + * `FIRST_PAGE`: + Integer, 1 if more than zero files were listed. + + * `LAST_PAGE`: + Integer, last page available if more than zero files were listed. + + * `PREVIOUS_PAGE`: + Integer, `CURRENT_PAGE` minus 1, if `CURRENT_PAGE` is bigger than 1. + + * `NEXT_PAGE`: + Integer, `CURRENT_PAGE` plus 1, if `LAST_PAGE` is bigger than `CURRENT_PAGE`. + +blogc(1) can output the value of the variables after evaluation, instead of +actually rendering the files, using the `-p` option. See blogc(1) for details. +This is useful to know the last page that needs to be built, using `-p LAST_PAGE`, +for example. + +### Date variables + +blogc(1) will also export some global blogc-template(7) variables related to +the `DATE` variable, as specified in blogc-source(7). + + * `DATE_FIRST`: + String, `DATE` variable from the first file in the listing. + * `DATE_LAST`: + String, `DATE` variable from the last file in the listing. + +These variables can be also formatted with `DATE_FORMAT` global blogc(1) parameter, +if provided, using `DATE_FIRST_FORMATTED` and `DATE_LAST_FORMATTED` global +template variables. + +### File name variables + +blogc(1) will also export some global blogc-template(7) variables related to +the `FILENAME` variable, as automatically exported by the source file parser, +see blogc-source(7) for details. + + * `FILENAME_FIRST`: + String, `FILENAME` variable from the first file in the listing. + * `FILENAME_LAST`: + String, `FILENAME` variable from the last file in the listing. + +## EXAMPLES + +### Source file with tags + + TITLE: My post + TAGS: foo bar baz + ----------------- + Post content + +This source file defines 3 tags: `foo`, `bar` and `baz`. + +### Template with pagination + + {% block listing_once %} +
    + {% ifdef PREVIOUS_PAGE %} + + {% endif %} + {% ifdef NEXT_PAGE %} + + {% endif %} +
+ {% endblock %} + +This example does not uses all the variables, but the concept is the same for +all of them. + +## BUGS + +Please report any issues to: + +## AUTHOR + +Rafael G. Martins <> + +## SEE ALSO + +blogc(1), blogc-source(7), blogc-template(7) diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn index c49f3ce..1a2cc76 100644 --- a/man/blogc-source.7.ronn +++ b/man/blogc-source.7.ronn @@ -45,6 +45,10 @@ You can omit seconds, minutes and hours if you want, they will be filled with The ``DATE_FORMAT`` variable should be passed to blogc(1) as a global variable. Its value must be a valid strptime(3) format. +The source parser will also automatically generate a variable called `FILENAME`, +that stores the name of the source file, without its extension. This is useful +for building permalinks in templates. + ## SOURCE CONTENT - BLOCK ELEMENTS ### Paragraphs diff --git a/man/blogc.1.ronn b/man/blogc.1.ronn index 7ee617f..baee026 100644 --- a/man/blogc.1.ronn +++ b/man/blogc.1.ronn @@ -44,7 +44,7 @@ designed to be used with make(1). * `-p` : Show the value of a global configuration parameter right after the source parsing and exits. This is useful to get parameters for your `Makefile`, - like the last page when using pagination. + like the last page when using pagination, see blogc-pagination(7) for details. * `-t`