sbs

commit 579fd8ce9a86b2c549bc7619e54ee4a1abf45cc5
parent f559095f3a5d380f1e68fd2c6d967927917a4350
Author: Jake Bauer <jbauer@paritybit.ca>
Date:   Tue, 15 Feb 2022 01:25:04 -0500

Update documentation

Diffstat:
M
README.md
 | 
51
++++++++++++++++++++++++++++++++++-----------------

1 file changed, 34 insertions(+), 17 deletions(-)
diff --git a/README.md b/README.md
@@ -1,24 +1,30 @@
-# SBS - Simple Blogging System
+# sbs - Simple Blogging System
 
 A simple static site generator designed to be simpler to use than existing
 solutions such as Hugo and Jekyll.
 
 # Usage
 
-`sbs [new [post|site]] file`
-
-1. Create a new site with `sbs new site <name>` where `<name>` is the name of
-   the directory under which your sites files will be;
-2. Enter the newly-created directory and alter alter `config.ini`,
-   `templates/header.html`, `templates/footer.html`, and `static/style.css` to
-   fit your site;
-3. Create a new page with `sbs new page <location>`. It will be placed into the
-   `content/` directory at the location specified (so if you specify
-   `blog/new-post` , the `blog/` directory should already exist);
-4. Run `sbs <files>` to build particular files. The output will appear under
-   `static/`;
-5. Use a utility like `rsync` to copy the contents of the `static/` directory to
-   your webserver.
+`sbs genfeed|[new [page|post|site]] file(s)`
+
+`sbs genfeed` will build an Atom feed from the posts under the configured
+`postsDir` directory. This feed will be output to `static/feed.xml`.
+
+`sbs new page <file>` will create the file `<file>` under the `content`
+directory with the basic layout for a regular page. Note that if a subdirectory
+is specified for `<file>`, this subdirectory must already exist.
+
+`sbs new post <file>` will create the file `<file>` under the `content/`
+directory with the basic layout for a blog post. Note that if a subdirectory is
+specified for `<file>`, this subdirectory must already exist.
+
+`sbs new site <file>` will create a new site structure under the directory
+`<file>` populated with sample files. These sample files should be edited to
+conform to the webmaster's needs. It is also recommended to create a
+`favicon.png` and `robots.txt` file.
+
+`sbs <file(s)>` will attempt to build the given `<file(s)>` and will place the
+output under the `static/` directory.
 
 Here's a quick example:
 
@@ -28,10 +34,22 @@ $ cd example.com
 $ vi config.ini templates/header.html templates/footer.html static/style.css
 $ sbs new page index.md
 $ vi content/index.md
-$ sbs index.md
+$ sbs content/index.md
+$ mkdir content/posts
+$ sbs new post blog/first-post.md
+$ vi content/blof/first-post.md
+$ sbs genfeed
 $ rsync static/* webserver:/var/www/
 ```
 
+## Troubleshooting
+
+`lowdown: <tag>: unknown keyword` - Lowdown tried to parse metadata tag `<tag>`
+but the tag was not found in the file. This is usually caused either by
+accidentally omitting a required tag, or leaving the content for a tag blank.
+Make sure that there is at least some text for each MultiMarkdown metadata tag
+in the file you are trying to build, and that all the required tags exist.
+
 ## Goals
 
 After trying out Hugo and the like, I found even the solutions that call
@@ -46,4 +64,3 @@ the bare minimum of what I need out of a blog.
 * Basic website styling -> One CSS file
 * Make writing posts and creating sites as painless as possible
 * Friendly configuration (i.e. simple config file)
-* Optional table of contents (three levels)