blog/README.md

108 lines
3.6 KiB
Markdown
Raw Normal View History

2017-10-08 03:13:31 +00:00
# Blog
2017-12-24 21:55:50 +00:00
This is a web blog and personal homepage engine written in Go. It includes a
full-featured web blog (with tags, archive views, etc.) and can serve static
web assets, Go HTML templates and Markdown pages.
## Zero Configuration
Blog is designed to be extremely easy to run: just give it a path to your
website's document root. It doesn't have to exist: it can be created as needed!
```
blog $HOME/www
```
See `blog -h` for command line arguments, for example to make it listen on a
different port number.
## Dual Template System
Whenever a web request is handled by the Blog program, it checks your
user-defined Document Root to serve the file before falling back on its
built-in store of "Core Files."
This way, you can copy and override files from the Core Root by creating files
with the same names in your Document Root. If you override `.layout.gohtml`,
you can customize the overall web design of your site. You can also
override individual templates to customize the look of built-in pages, such as
how blog entries are formatted.
The Blog has a built-in page editor that makes it easy to copy and override
the core template files.
## Render Go HTML and Markdown Files
You can write pages in the Go [html/template](https://golang.org/pkg/html/template/)
format (`.gohtml`) or in GitHub Flavored Markdown (`.md`). Markdown pages will
be rendered to HTML and inserted into your web design layout like normal pages.
## Built-in Page Editor
A built-in editor lists all of the pages in your Document Root and the Core
Root. You can click on a page to edit it, with the
[ACE Code Editor](https://ace.c9.io/) offering a rich code editing experience,
with syntax highlighting for HTML, Markdown, JavaScript and CSS.
Editing a Core Page and saving it will save an override version in your
Document Root.
In the default Blog theme, every page includes a link to edit the page
in the Page Editor for logged-in users. The 404 Error handler also
provides shortcuts to create a new page at that path.
2017-10-08 03:13:31 +00:00
# Setup
```bash
# If you're new to Go, set your GOPATH.
export GOPATH="${HOME}/go"
# Clone this repository to your go src folder.
git clone https://github.com/kirsle/blog ~/go/src/github.com/kirsle/blog
cd ~/go/src/github.com/kirsle/blog
# Run the server
make run
2017-12-24 21:55:50 +00:00
# Or to run it manually with go-reload to provide custom options:
./go-reload cmd/blog/main.go [options] [/path/to/document/root]
2017-10-08 03:13:31 +00:00
```
2017-12-24 21:55:50 +00:00
## Recommendation: Redis
It is recommended to use the [Redis](https://redis.io) caching server in
conjunction with Blog. Redis helps boost the performance in two main areas:
The JSON database system will cache the JSON documents in Redis, speeding up
access time because the filesystem doesn't need to be read each time. If you
manually modify a JSON file on disk, it _will_ notice and re-read it next time
it's requested.
If you make use of source code blocks in GitHub Flavored Markdown, the Python
`pygmentize` command can render syntax-highlighted HTML from it. Calling this
program takes ~0.6s, and a page with many source blocks would take a _long_ time
to load. I alleviate this by MD5-hashing and Redis-caching the rendered HTML
code to minimize calls to `pygmentize`.
After you initialize the site, go to the admin settings to enable Redis.
## Syntax Highlighting with Pygments
To enable syntax highlighting within Markdown files (like with GitHub Flavored
Markdown), install [pygments](http://pygments.org) on your system. For example:
```
# Fedora/RHEL
sudo dnf install python3-pygments python3-pygments-markdown-lexer
# Debian
sudo apt install python3-pygments
```
2017-12-24 21:55:50 +00:00
Blog will automatically use the `pygmentize` command if it's available on its
`$PATH`.
2017-10-08 03:13:31 +00:00
# License
MIT.