diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/blogc-git-receiver.1.ronn | 126 | ||||
| -rw-r--r-- | man/blogc-pagination.7.ronn | 122 | ||||
| -rw-r--r-- | man/blogc-runserver.1.ronn | 48 | ||||
| -rw-r--r-- | man/blogc-source.7.ronn | 31 | ||||
| -rw-r--r-- | man/blogc.1.ronn | 4 | ||||
| -rw-r--r-- | man/index.txt | 18 |
6 files changed, 341 insertions, 8 deletions
diff --git a/man/blogc-git-receiver.1.ronn b/man/blogc-git-receiver.1.ronn new file mode 100644 index 0000000..e26ed09 --- /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`) <user> + +## 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: <https://github.com/blogc/blogc> + +## AUTHOR + +Rafael G. Martins <<rafael@rafaelmartins.eng.br>> + +## SEE ALSO + +blogc(1), git(7), chsh(1), su(1), make(1) 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 %} + <ul class="pager"> + {% ifdef PREVIOUS_PAGE %} + <li class="previous"> + <a href="/page/{{ PREVIOUS_PAGE }}/">← Newer</a> + </li> + {% endif %} + {% ifdef NEXT_PAGE %} + <li class="next"> + <a href="/page/{{ NEXT_PAGE }}/">Older →</a> + </li> + {% endif %} + </ul> + {% 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: <https://github.com/blogc/blogc> + +## AUTHOR + +Rafael G. Martins <<rafael@rafaelmartins.eng.br>> + +## SEE ALSO + +blogc(1), blogc-source(7), blogc-template(7) 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` <HOST>] [`-p` <PORT>] <DOCROOT><br> +`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` <HOST>: + HTTP server listen address, defaults to `127.0.0.1`. + + * `-p` <PORT>: + HTTP server listen port, defaults to `8080`. + + * `-v`: + Show program name, version and exit. + + * `-h`: + Show help message and exit. + +## ARGUMENTS + + * <DOCROOT>: + HTTP server document root. + +## BUGS + +Please report any issues to: <https://github.com/blogc/blogc> + +## AUTHOR + +Rafael G. Martins <<rafael@rafaelmartins.eng.br>> + +## SEE ALSO + +blogc(1) diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn index 7fa0796..b583d6e 100644 --- a/man/blogc-source.7.ronn +++ b/man/blogc-source.7.ronn @@ -45,6 +45,15 @@ 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. This variable can't be overriden by an +explicit definition in source file. + +Another variable, `DESCRIPTION`, will be automatically created by the source +parser. Its content is the first line of the first paragraph of the content. +This variable can be overriden by an explicit definition in source file. + ## SOURCE CONTENT - BLOCK ELEMENTS ### Paragraphs @@ -203,18 +212,35 @@ Images are defined using the following syntax: This is an image:  +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: 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: [](https://blogc.rgm.io) +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) + ### Automatic Links Automatic link is defined with 2 '[' before and 2 ']' after the URL. @@ -226,6 +252,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 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` <KEY>: 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` <TEMPLATE>: Template file. It is a required option, if `blogc` needs to render something. @@ -93,4 +93,4 @@ Rafael G. Martins <<rafael@rafaelmartins.eng.br>> ## SEE ALSO -blogc-source(7), blogc-template(7), make(1), strptime(3) +blogc-source(7), blogc-template(7), blogc-pagination(7) make(1), strptime(3) diff --git a/man/index.txt b/man/index.txt index a85e2a0..4ca6e67 100644 --- a/man/index.txt +++ b/man/index.txt @@ -1,9 +1,15 @@ # 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-runserver(1) blogc-runserver.1.ronn +blogc-source(7) blogc-source.7.ronn +blogc-template(7) blogc-template.7.ronn +blogc-pagination(7) blogc-pagination.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) |