blogbuilder

BlogBuilder is a generator for static blogs written in Java
git clone https://git.ortlepp.eu/blogbuilder.git
Log | Files | Refs | README | LICENSE

Getting-Started.md (10967B)


      1 This Wiki page shows step by step how to use BlogBuilder.
      2 
      3 # Setting up BlogBuilder
      4 To run BlogBuilder, no special setup is required except Java must be present on the computer in at least version 8. To verify that BlogBuilder works properly, navigate in a console  to the directory where the downloaded JAR file is located. Run `java -jar BlogBuilder.jar`, which should print out usage instructions for BlogBuilder.
      5 
      6 You can always run BlogBuilder as shown above. But to make things more comfortable it is possible to *install* BlogBuilder:
      7 
      8 ## Optional installation on Windows
      9 Find a place to keep BlogBuilder, for example in `C:\BlogBuilder`. The downloaded JAR file has to be in that folder. Afterwards, create a new file `BlogBuilder.cmd` in this folder and fill it with this line:
     10 
     11     java.exe -jar C:\BlogBuilder\BlogBuilder.jar %*
     12 
     13 Finally add `C:\BlogBuilder` to the `PATH` variable. In CMD and PowerShell BlogBuilder is now available, to try it, run `BlogBuilder` from the command-line.
     14 
     15 ## Optional installation on Linux
     16 Create the directory `/opt/BlogBuilder` and copy the downloaded JAR file in this folder. In this folder, create a new shell script `BlogBuilder.sh` with this content:
     17 
     18     #!/bin/bash
     19     java -jar /opt/BlogBuilder/BlogBuilder.jar "$@"
     20 
     21 Now make the shell script executable and link it to `/usr/bin`:
     22 
     23     chmod +x /opt/BlogBuilder/BlogBuilder.sh
     24     ln -s /opt/BlogBuilder/BlogBuilder.sh /usr/bin/BlogBuilder
     25 
     26 BlogBuilder is now available, to try it, run `BlogBuilder` from the command-line.
     27 
     28 
     29 # Creating a new project
     30 The best way to start a new project is to let BlogBuilder do all the setup. When BlogBuilder is launched with the argument `--init`, a new project is created.
     31 
     32     java -jar BlogBuilder.jar --init MyBlog
     33 
     34 creates a new project *MyBlog* in the current directory. Alternatively
     35 
     36     java -jar BlogBuilder.jar --init C:/Users/example/MyBlog
     37 
     38 creates a new project *MyBlog* in the personal folder of the user *example*. BlogBuilder accepts absolute and relative directory paths as long as the project directory itself does not yet exist.
     39 
     40 When the initialization action runs, it creates the project directory, some sub-directories and a bunch of sample files. After the creation is done, go to the project directory - there you will find these directories:
     41 
     42 | Directory / File | Usage                                                               |
     43 |:-----------------|:--------------------------------------------------------------------|
     44 | blog             | Contains the built blog, *empty when a new project is started*      |
     45 | content          | Contains all Markdown files (blog posts and pages)                  |
     46 | resources        | Contains additional resources (CSS & JavaScript files, images, ...) |
     47 | templates        | Contains templates for the Markdown to HTML processing              |
     48 | blog.properties  | The configuration file for the project / blog                       |
     49 
     50 Do not rename or delete these directories - BlogBuilder expects them to exist and will fail to build the blog if a directory is missing.
     51 
     52 ## The directory "blog"
     53 This directory contains the build blog after the build action run. Upload the contents of this directory to you web space to publish the blog.
     54 
     55 ## The directory "content"
     56 This directory contains all blog posts and content pages in Markdown format. When the build action runs, it will process these files to HTML pages. Only files with the extension `.md` are processed to HTML, all other files are ignored.
     57 
     58 It is possible to create sub-directories; created sub-directories will become part of the URL of the HTML page, for example the directory `2017` is created and the blog post `hello_world.md` is placed in that directory, then the URL of the blog post will be `[BLOG-URL]/2017/hello_world.html`.
     59 
     60 ## The directory "resources"
     61 This directory contains additional resources for the blog, e.g. CSS files, custom JavaScript libraries, images, fonts, ... All files are copied to the `blog` directory when the blog is built. It is also possible to create sub-folders and place resource files in these sub-directories. All files are copied by keeping their path, for example the file `resources/style/style.css` is copied to `blog/style/style.css` and its URL will be `[BLOG-URL]/style/style.css`.
     62 
     63 ## The directory "templates"
     64 This directory contains the FreeMarker template files that are used to create the HTML pages. You can edit these files to change the layout of the blog (see [[Advanced Features]]). But do not rename or delete the template files that are starting with the `page_` prefix as BlogBuilder expects these to exist in the template directory.
     65 
     66 ## The file "blog.properties"
     67 This file configures your blog. For a detailed description of all options see "Configuring the blog" below.
     68 
     69 
     70 # Writing blog posts and creating pages
     71 All Markdown files in the directory `content` (including sub-directories) are treated as Blog posts or content pages. To edit or create these files, you can either use a common text editor (e.g. [Notepad++](https://notepad-plus-plus.org/)) or a special Markdown editor (e.g. [MarkdownPad](http://markdownpad.com/)).
     72 
     73 Each file has a header and a content part. Each line of the header starts with `;;` and contains a key-value-pair. These headers are supported by BlogBuilder:
     74 
     75 | Header (key) |    Example value   | Obligatory |                     Explanation                     | Additional comment                                               |
     76 |:------------:|:-------------------|:----------:|:----------------------------------------------------|:-----------------------------------------------------------------|
     77 | `title`      | `Hello World`      | yes        | The title of the blog post or page                  | Just plain text, Markdown is not supported                       |
     78 | `created`    | `2017-07-28 23:14` | yes        | The creation date and time of the blog post or page | Has to be formatted as shown<br>Do not change after publishing   |
     79 | `modified`   | `2016-07-29 15:53` | no         | The last modification of the blog post or page      | Has to be formatted as shown                                     |
     80 | `category`   | `General, Blog`    | no         | The categories of a blog post                       | Separate multiple categories with `,`<br>Only used in blog posts |
     81 | `noblog`     | *(no value)*       | no         | Indicator for content pages                         | Does not have a value                                            |
     82 
     83 The obligatory headers have to be in a file, otherwise it will be ignored in the build process. It is recommended not to change the creation date and time after the blog post or page has been published; instead use the modification date and time to indicate updates or changes.
     84 
     85 All lines that don't start with `;;` are treated as content lines. During the build process the Markdown formatting is parsed and transformed into HTML.
     86 
     87 When a file is saved, pay attention that its encoding is set to UTF-8. If not, there might occur problems while reading the file in the build process.
     88 
     89 
     90 # Configuring the blog
     91 To configure the blog, open the `blog.properties` in a text editor:
     92 
     93 |       Option        |       Default value       |                        Explanation                         |                                   Additional comment                                    |
     94 |:-------------------:|:-------------------------:|:-----------------------------------------------------------|:----------------------------------------------------------------------------------------|
     95 | `blog.title`        | `My Blog`                 | The title of the blog                                      |                                                                                         |
     96 | `blog.author`       | `John Doe`                | The author of the blog                                     |                                                                                         |
     97 | `blog.baseurl`      | `http://blog.example.com` | The base URL of the blog                                   | A URL like `https://example.com/blog` is possible as well                               |
     98 | `blog.locale`       | `en-US`                   | The locale to use for number and date formats              |                                                                                         |
     99 | `index.filename`    | `index`                   | The filename of the index file(s)                          | Only the prefix, optional page number and the extension `.html` are added automatically |
    100 | `index.posts`       | `3`                       | The number of blog posts on each index page                |                                                                                         |
    101 | `feed.filename`     | `feed.xml`                | The filename of the feed                                   |                                                                                         |
    102 | `feed.posts`        | `3`                       | The number of blog posts in the feed                       |                                                                                         |
    103 | `category.filename` | `category_`               | The filenames of the category pages                        | Only the prefix, category names and the extension `.html` are added automatically       |
    104 | `sitemap.filename`  | `sitemap.xml`             | The filename of the sitemap                                |                                                                                         |
    105 | `clean.ignore`      | `.gitkeep`                | Files in the `blog` folder that are ignored while cleaning | Separate multiple files with `;` (without spaces)                                       |
    106 
    107 If an option is missing (or misspelled) in the configuration file, its default value is used. The file itself is an ordinary Java properties file. Empty lines are ignored, lines that start with `#` are treated as comments.
    108 
    109 
    110 # Building the blog
    111 To publish the blog, it has to be built first. Building the blog means, that all blog posts and content pages are processed to HTML pages, additional files (index and category pages, the feed and the sitemap) are generated and all resources are copied into the blog. To build the blog, launch BlogBuilder with the argument `--build`. For example, run
    112 
    113     java -jar BlogBuilder.jar --build MyBlog
    114 
    115 to build the project *MyBlog* (*MyBlog* is the project directory of the blog).  Like the `--init` action, an absolute path to the project directory is sufficient as well.
    116 
    117 When the build process is done, the blog can be uploaded to a webserver in order to get published.
    118 
    119 *Note: When the build process runs, it first deletes all files in the `blog` directory and then rebuilds the entire blog. To keep certain files, use the option `clean.ignore` in the configuration file.*