go.charczuk.com@v0.0.0-20240327042549-bc490516bd1a/projects/blogctl/README.md (about)

     1  blogctl
     2  =========
     3  
     4  # Overview
     5  
     6  `blogctl` is a streamlined system for publishing a photo blog as a static site (on s3 or similar). The primary UI is the `blogctl` commandline utility.
     7  
     8  It's what I use to make [charczuk.com](http://www.charczuk.com).
     9  
    10  # Installation
    11  
    12  * Make sure you have golang installed
    13  	- see: [Golang Installation Instructions](https://golang.org/doc/install) for more detail.
    14  * From a commandline, run:
    15  	```bash
    16  	> go get go.charczuk.com/projects/blogctl
    17  	```
    18  
    19  You should now be able to create a blog and publish it.
    20  
    21  # Blog Structure
    22  
    23  There are a couple main things that are required to build a blog with `blogctl`.
    24  
    25  These are contained within the blog's `config.yml` (found at the root of the blog, a file in YAML encoding):
    26  - `outputPath` Where the blog will be built (defaults to `./dist`)
    27  - `postsPath` Where blogctl reads posts (defaults to `./posts`). Posts should be in their own folder and appear in the order in the blog they appear on disk.
    28  	* A post consists of:
    29  		- The image file (must be a `.jpg`).
    30  		- `meta.yml` Where you can specify things like the posted date, the title, the location, commands and tags.
    31  - `postTemplate` Where the html template for each post lives (defaults to `layout/post.html`)
    32  - `tagTemplate` Where the html template for each tag's posts lives (defaults to `layout/tag.html`)
    33  - `pagesPath` A path to a directory of pages to render (defaults to `layout/pages`). Typically includes `index.html`, or the root page.
    34  - `partialsPath` A path to a directory of partials to include when rendering pages or the `post` or `tag` template.
    35  - `staticPath` A path to a directory of static files to copy as is to the `outputPath`. Typically stuff like javascript and css files and other image assets.
    36  - `s3` Options for deploying to s3 like the `bucket` and the `region`.
    37  - `cloudfront` Options for caching with `cloudfront`, includes options like the `distribution`.
    38  
    39  There are some extra paths that
    40  
    41  # `blogctl` usage
    42  
    43  With `blogctl` you can initialize a new blog, create a new post, compile the blog to the output directory, and publish it to s3.
    44  
    45  It reads from `config.yml` and then files on disk.
    46  
    47  Main Commands:
    48  - `blogctl init` Creates a new blog from scratch with a functioning gallery and (1) sample post, and creates a `config.yml` for you.
    49  - `blogctl new` Creates a new post from a given file (must be run in your blog's directory).
    50  - `blogctl build` Compiles posts found in your `postsPath`
    51  
    52  See: `blogctl --help` for more info.
    53  
    54  # Other stuff
    55  
    56  `blogctl` uses golang's great `html/template` package to generate the site. More docs on `html/template` can be found [here](https://godoc.org/html/template)