Pokology - a community-driven site around GNU poke

_____ ---' __\_______ ______)

Contributing to the site

__) __) ---._______) Table of Contents _________________ 1. Getting access to pokology.git 2. Contents of pokology.git 3. Altering the contents of an existing page 4. Creating new pages 5. Hints on formatting *Pokology* is made by the GNU poke community: developers, users and friends. Anybody is very welcome to add new content and to improve the existing pages. This page describes how. 1 Getting access to pokology.git ================================ The contents of *Pokology* are written in Org mode files (https://orgmode.org) and stored in a git repository hosted on ageinghacker.net: http://git.ageinghacker.net/pokology You can clone a read-only version of the site via HTTP, like this: ,---- | $ git clone http://git.ageinghacker.net/pokology `---- Cloning via HTTP requires no authentication or authorisation. However in order to contribute to the site you will need write access to the git repository. To obtain it, please write an email to poke-devel@gnu.org requesting access to Pokology. Someone will promptly get back to you, and ask you for several details including a public SSH key. Once you have write access, you must be able to clone a write-enabled working copy of the repository, via SSH: ,---- | $ git clone git@ageinghacker.net:/pokology.git `---- 2 Contents of pokology.git ========================== The layout of the site is very simple. You will find the following kind of files in the repo: - Org-mode files that use the extension .org. These are the files that provide the contents of the site, and that at some point get processed to generate corresponding HTML files. - A CSS file pokology.css, which provides the style applied in the entire site. - A couple of scripts pull-pokology.sh and publish-pokology.sh, which are used at the server side in order to generate the HTML pages from the Org-mode sources. As an author, you will be mostly concerned with the Org-mode files. 3 Altering the contents of an existing page =========================================== Editing the contents of an existing page FOO.html involves to edit the corresponding FOO.org file. The best way to edit Org-mode files is with Emacs, but other editors (like VI derivatives) have also support for the format. Any text editor will do the work. Once you are happy with the changes in the .org files, commit the changes and push them to ageinghacker.net. A cron job in the server will eventually pick up your changes and regenerate the .html files accordingly. 4 Creating new pages ==================== Creating new pages is also easy: just add a new .org file to the top-level directory; you can also create sub-directories. When adding new files, use a header similar to this: ,---- | #+title: SOME TITLE | #+email: poke-devel AT gnu DOT org | #+language: en | #+category: pokology | #+options: H:3 \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) author:nil `---- Then commit and push the change to ageinghacker.net. A cron-job will pick up the new files and generate HTML for them. 5 Hints on formatting ===================== The formatting and structuring tags (emphasis, sections, subsections, tables, etc) you can use in .org files are fully documented in the Org-mode manual (https://orgmode.org/manual). Some recommendations when writing Pokology contents: - If you don't want a table of contents then specify toc:nil at the #+options header line. - If you don't want numbered sections and subsections then specify num:nil at the #+options header line. - Use links like file:foo/bar.org in order to link to other Pokology pages.