# How to ... with SBWG?

## How to set up a new website?

SBWG comes with an `examples` directory which contains the source files of a small web site that can be built with SBWG. You can copy this directory and build your
web site according to the example. Please read the INSTALL file for a instructions on how to set up a new website based on the example web site.


## How to post a new blog entry?

Create a entry source file in the `entries` directory. The file should start with tags that provide meta information like the entry's title, creation date,
categories and so on. Everything below that is the content of the entry. There is a more detailed description of the available tags in the "Tags" section in the
README file.

You can create this file from scratch, use the `genentry` script that is included in this package, copy an existing entry file or find your own way of creating new
files locally or on the web server. It's just a text file. There are many possibilities like using templates in your favourite text editor or writing your own
script that generates a new entry.

The next time the web site is generated, the new entry will be included in the weblog view and on the tagpages for the tags that you defined in the entry file.


## How to publish all changes?

After you have created new or changed existing content, you have to re-generate the website. There are different options for (re-)generating only galleries, the
blog, static pages, etc. To re-generate the entire website, use the option `-c` or `--complete`.

`sbwg -c`

This command will use the default input directory that is hardcoded in the script and put the generated output into the `html` subdirectory indide the input
directory. You can define the input and output directories with the options `-i` or `--input` and `-o` or `--output`:

`sbwg -c -i ~/blog -o /var/www/html`

Without the option -v (or --verbose) there will be now output to stdout if sbwg was successful.



## How to find entries on the command line?

You can use all tools you would usually use to search text files on a unix-like system. Here are a few examples that might be useful in certain situations.

0. List all entries with the tag "cat:incomplete".
	`grep -l cat:incomplete ../../my_weblog/entries/*`

1. List all entries without a defined creation date.
	
	

2. List all stickied posts.
	


3. List all entries that have been changed in the last 5 days according to the file information.
	


4. List all entries that have been edited according to the "edited:" tags inside them.
	

5. 


## How to maintain a development/staging website?

You can make use of the `-o` or `--output` option to place the generated web site in a different directory from what is specified in the web site's settings file. If
both the option and the setting are omitted, the script puts the generated web site in the `html` directory inside the source/input directory. A way to maintain
different output directories without having to type them every time is to use aliases.

Example:

`alias sbwg-live='sbwg -o /var/www/html'

`alias sbwg-dev='sbwg -o "${HOME}/weblog_staging"'


## How to change stylesheets and apply changes or create my own CSS?

Create your own style with the name "mystyle", create a file named `mystyle.css` in the `styles` directory inside your website source directory. Fill it with
whatever styles you would like applied to all of your generated website, then build the website with the option `-s mystyle`.

For example: `genlog -c -i /path/to/source/dir -s mystyle`

If you want to create a more complex style, you can split the rules into multiple files. Every file with a name starting with the style name followed by a hyphen
and ending in .css will be used as well. So for example you can split your CSS rules into the files `mystyle.css`, `mystyle-colors.css`, `mystyle-galleries.css`,
`mystyle-whatever.css`. All those files will be linked in every generated HTML page.



## How to edit an entry without changing its edited date?

Option 1:
	edit() {> file=$1; mtime=$(stat -c %y "$file"); nano "$file"; touch -d "$mtime" "$file"> }
	edit THE_FILE_YOU_WANT_TO_EDIT
	# Change editor according to your preferance
	# You might want to add this function to your dotfiles ;)

Option 2:
	touch -r ENTRYFILE /tmp/timestamps.tmp
	nano ENTRYFILE
	touch -r /tmp/timestamps.tmp ENTRYFILE
	# Change editor according to your preferances



## How to update the website after changes without re-generating the entire site?

If you only want to publish the changes in the content of an edited page or entry (no new entry or page needs to be generted and tags have not been changed) then you
can use the options `-p` or `--pages` for pages and `-e` or `--entry` for entries. Using one of these option without an argument will (re-)generate all pages/
entries. Adding the name of an entry/page will only (re-)generate that page/entry.

Examples:

`genlog -i /path/to/source/dir -e entry_name`
`genlog -i /path/to/source/dir -e "file name of entry"`
`genlog -i /path/to/source/dir --entry blog_post_2020-12-24`
`genlog -i /path/to/source/dir -p "Page Name"`
`genlog -i /path/to/source/dir --page frontpage`

If other changes have been made to the website source (i.e. changes in tags, new entries or pages), the entrie blog needs to be re-generated.

Example: `genlog -c -i /path/to/source/dir`



## How to make a website that resides in a subdirectory?

If your website will not be served from the web server root (i.e. not https://www.example.com/ but https://www.example.com/mywebsite/) then you have to specify it's
path when generating the website using the option `-w` or `--webpath`. The webpath should always be the full path after the domain name to the directory where the
root index.html will be located, including the preceding and trailing slashes.

Examples:

`genlog -c -i /path/to/source/dir -w /mywebsite/`
`genlog --complete -input /path/to/source/dir -webpath /mywebsite/`

In this example the website's homepage will be accessible at `https://www.example.com/mywebsite/index.html`.





How long does it take to generate a website?
How to share content between otherwise independent web sites?
How to list entries with a certain tag?
