ltlnx’s Blog Updater
This is ltlnx’s blog updater: it takes a source directory with Markdown files, a “header” and a “footer”, converts them to HTML, and copies them to the desired destination directory.
A fully-fledged demo that uses this generator can be found at https://ltlnx.tw. (That’s the site you’re looking at!)
GitHub repo link Script direct download
Prerequisites
- any bourne-compatible shell (tested with ksh, bash, ash, dash, and sh)
- GNU grep (or a grep supporting
-P) - GNU sed
- Pandoc for Markdown conversion, or you can edit the
vmdconvcommandto supplant with your own Markdown convertor.
There may be something missing here but in general, a Linux system with pandoc installed would probably work. (If not, please create an issue.)
Setup (on Linux)
- Open a terminal and clone this repo.
- Go into the cloned directory:
cd ltlnx-blog-updater - Make sure the script is executable:
chmod u+x update.sh - Initialization:
./update.sh init. At this point a minimal blog example would be created. - Edit details in the
.updatercfile as necessary. - Run the script again.
- Copy the generated files to your web server directory, or if you
have python3 installed, run
./update.sh serveand go to 0.0.0.0:8000 with your preferred web browser.
Editing the config file
The config file, .updaterc, contains all parameters the
script needs. The comments in the file should be self-explanatory, but
here are some tips:
- For
vroot, if you plan to run the script from another directory, please substitute it with an absolute path (i.e./home/ltlnx/bloginstead of.). - It would be beneficial to explore the different Markdown flavors
pandoc supports, and determine the actual
vmdconvcommandyou want to use. For https://ltlnx.tw I usepandoc -f commonmark-x -t html.
Writing blog posts and tag descriptions
Both blog posts and tag descriptions should be Markdown files in the
source directory (src by default). Blog posts have the
suffix .md, and descriptions have the suffix
.desc. Say if you want to add a new tag named “tech”:
Write a blog post and add
Tags: techat the end of the file (or anywhere beneath the title).In the source directory, add a file named
tech.desc.Add to the file a description that looks like the following:
# Tech-related stuff Here are all my tech-related stuff.Rebuild the blog by running
update.sh.
After running, you should ba able to go to
dst/tags/tech.html to make sure that it’s applied, and has
a link to the blog post.
Header and footer files
The header and footer files in the root
directory is the HTML that would be added to the top and bottom of pages
on the website, making the HTML complete. The header file
should end with a opening tag (like <div id="main">),
and the footer file should start with a closing tag with
the same type as the opening tag (like </div>). The
example header and footer files are minimal
examples of what they look like.
Dates
To specify the date of a post, you can do one of the following:
- Add a date on its own line, e.g.
2023-11-03 - Add a date after “Last updated: “, e.g.
Last updated: 2023-11-03
Both would work equally fine. Just make sure that you don’t specify two dates for the same post, or the updater script would pick the first one.
Sticky posts
If the post is in the src/sticky folder, it wouldn’t
show up in the archive.html page but still show up in the
tag pages. Useful for the homepage (src/sticky/index.md),
about page (src/sticky/about.md) and the like.
“Theming”
To “theme” your site, add a CSS file, preferably named
style.css, in the source directory. A minimal example is
included after you run ./update.sh init. You can inspect
the generated HTML (with Firefox’s inspector, a text editor or whatever)
and determine which target to write styles for.
Don’t forget to add a <link> attribute to the
header file, which looks like such:
<link rel="stylesheet" type="text/css" href="/style.css">RSS (Atom) and a sitemap
This script also generates an RSS feed named “atom.xml” in the
destination directory. You can decide what to do with it. When deploying
with the script, a “sitemap.xml” will be generated, or you can generate
it manually by running ./update.sh gensitemap.
Contributing / Bug reports
This script currently doesn’t accept pull requests, but you’re welcome to report bugs in Github Issues or directly to ltlnx dot tw at gmail dot com. Thanks for discovering and using my script!
– ltlnx 2023-11-27