Merge pull request #1 from snonux/master

Master

1 files changed, 110 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e162309
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+The buetow.org internet site
+============================
+
+This is the source code of my personal internet site and blog engine. All content is written in Gemini Gemtext format, but the script `buetow.org.sh` generates multiple other static output formats from it. You can reach the site(s)...
+
+* Via Gemini/Gemtext: [gemini://buetow.org](gemini://buetow.org) (You need a Gemini client for this)
+* Via "normal" HTML: [https://buetow.org](https://buetow.org) (Actually it's XHTML Transitional 1.0)
+* Via [Gemini Webproxy](https://portal.mozz.us/gemini/buetow.org)
+* Via [GitHub Markdown](https://github.com/snonux/buetow.org/blob/content-md/index.md)
+* Via [GitHub Page](https://snonux.github.io/buetow.org) (from Markdown)
+
+Have a look at the `content-*` branches of this buetow.org Git project for source samples.
+
+## Software I use to maintain this site
+
+* Text editor: [Vim](https://www.vim.org)
+* Gemini server: [a-h/gemini](https://github.com/a-h/gemini)
+* Bash
+* ShellCheck (if you want to run the tests)
+* Web server: [Apache HTTPD](https://httpd.apache.org) (for "normal" HTML site)
+* Obviously, I am also using GitHub for source code and GitHub Page hosting.
+
+# Getting started
+
+## Requirements
+
+These are the requirements of the `buetow.org.sh` static site generator script:
+
+* GNU Bash 5.x or higher
+* ShellCheck installed
+* GNU Sed
+* GNU Date
+* Git
+
+The script was tested on a recent Fedora Linux. For *BSD or macOS you would need to install GNU Sed, GNU Date, and a newer version of Bash.
+
+## Usage
+
+So you want such a pretty internet site too?
+
+To get started, just clone this repo (master branch) and run `./buetow.org.sh`. You will will be prompted with further instructions.
+
+You will notice soon, that all site content is located in `../buetow.org-content/` (you can configure the `BASE_CONTENT_DIR` in `buetow.org.conf`). There is one sub-directory per output format, e.g.:
+
+```
+../buetow.org-content/gemtext
+../buetow.org-content/html
+../buetow.org-content/md
+../buetow.org-content/meta
+```
+
+### Alternative config file path
+
+If you don't want to mess with `buetow.org.conf`, you can use an alternative config file path in `~/.config/buetow.org.conf`, which takes precedence if it exists. Another way is to set the `CONFIG_FILE_PATH` environment variable, e.g.:
+
+```
+export CONFIG_FILE_PATH=~/.config/my-site.geek.conf
+./buetow.org.sh --generate
+```
+
+### What is what
+
+Whereas, you only want to directly edit/add/remove content in the `gemtext` folder. The `buetow.org.sh` then will take the Gemtext and update all other formats accordingly. Summary of what is what:
+
+* `gemtext`: The Gemini Gemtext markup files of the internet site.
+* `html`: The XHTML version of it.
+* `md`: The Markdown version of it. 
+* `meta`: Some meta data of all Gemtext blog posts. It's used by `buetow.org.sh` internally for Atom feed generation.
+
+### Special HTML configuration
+
+You will find the `./header.html.part` and `./footer.html.part` files, they are minimal template files for the HTML generation.
+
+### Special Markdown configuraiton
+
+`buetow.org.sh` will never touch the `../buetow.org-content/md/_config.yml` file (if it exists). That's a special configuration file for GitHub Pages.
+
+## Store all formats in Git
+
+I personally have for each directory in `../buetow.org-content/` a separate Git repository configured. So whenever something has changed it will be updated/added/removed to version control. The following will run the generator and commit everything to Git:
+
+```
+USE_GIT=yes ./buetow.org --generate
+```
+
+And the following will additionally perform a `git pull` and `git push` afterwards;
+
+```
+USE_GIT=yes GIT_PUSH=yes ./buetow.org --generate
+```
+
+You could add the `USE_GIT` and `GIT_PUSH` options to the `buetow.org.conf` config file too.
+
+## Publishing a blog post
+
+All what needs to be done is to create a new file in `./gemtext/gemfeed/YYYY-MM-DD-article-title-dash-separated.gmi`, whereas `YYYY-MM-DD` defines the publishing date of the blog post.
+
+A subsequent `./buetow.org.sh --generate` will then detect the new post and link it from `$BASE_CONTENT_DIR/gemtext/gemfeed/index.gmi`, link it from the main index `$BASE_CONTENT_DIR/gemtext/index.gmi`, and also add it to the Atom feed at `$BASE_CONTENT_DIR/gemtext/gemfeed/atom.xml`. The first level 1 Gemtext title (e.g. `# Title`) will be the displayed link name. `YYYY-MM-DD` will be the publishing date. There are various other settings, such as Author - they come from the `buetow.org.conf` configuration file.
+
+Once all of that is done, the `buetow.org.sh` script will convert the new post (plus all the indices and the Atom feed) to the other formats too (e.g. HTML, Markdown).
+
+You can also have a look at `$BASE_CONTENT_DIR/meta/gemfeed`. There is a meta file for each blog post stored. These meta files are required for the generation of the Atom feed. You can edit these meta files manually and run `./buetow.org.sh --generate` or `./buetow.org.sh --feed` again, in case you want to change some of the Atom feed content.
+
+## Finito
+
+After running `./buetow.org --genreate` you will have all static files ready to be published. But before you do that you could preview the content with `firefox ../buetow.org-content/html/index.html` or `glow ../buetow.org-content/md/index.md` (you get the idea).
+
+Have also a look at the generated `atom.xml` files. They make sense (at least) for Gemtext and HTML.
+
+Now it is up to you to setup a Gemini server for the Gemtext, a Webserver for the HTML and/or a GitHub page for the Markdowns.