This blog is a static site compiled into HTML by Pelican. The Pelican folks have some docs on writing content. It should be applicable to this site, but might differ because we customized a theme for use here. Any deviation should be noted in this page. If you find one that isn't noted, it's a bug that should be fixed in our installation or by documenting it on this page. Feel free to improve this page. It is at content/pages/authoring.md in the repo.

We store the site and its posts in a git repository. If you don't know git, you cannot directly contribute a post, though you could probably write it in markdown and somebody could post it for you. To get started, check out the blog repo then change directory to where the posts are:

git clone git@code.librehq.com:ots/ots-blog.git
cd ots-blog/website/content/posts

To write a page, just make a new file. You can write in either markdown or reStructuredText. Follow the guide at docs and you should be fine.

When you're done, commit up your changes and push to the repo. Your changes are now safely stored in the cloud, but you haven't published yet. You can ask others to look at your post, edit it, do multiple rounds of fixing it, etc.

GO LIVE!

When you are ready to publish, there is a directory labelled bin. In it, there is a script, bin/push that will rsync your changes to https://blog.opentechstrategies.com. It will only do that rsync if your git tree is clean, so run git status and make sure you've committed up. Likewise, you can only push from the main branch. We have those safety checks in place to ensure that when the next person goes live, they have the same content on their drive as you do. Otherwise, after they bin/push, the live site will not contain all your changes.

Because the checks on your repository state can impede workflow, do your development in branches so you can check them in as WIP and switch to main for the push. That way, if you have in-progress work that isn't ready to go live, it can safely live in a branch where it won't get in the way.

Media

If you have any pictures to include, add it to a directory in uploads. Make a directory like uploads/<year>/<month>. Specify the month as a two-digit number with a leading zero if needed. Place your file in that directory. You can refer to it in your blog post with a url of {{SITEURL}}/uploads/<year>/<month>/<filename>.

Metadata

We use the standard metadata, plus some fields not noted in the Pelican docs.

• headerimage: --- Place an image at the top of your article on both the article page and in the index.

• headerimagealt: --- Add alt text to your header image. Please add alt text. It makes our website more accessible. If you see any images on this site that do not have alt text, please add some in the git repo.

• indeximage: --- Place an image above the article's entry on the index page, but not on the full text article page. An example of this can be seen in the checklist.md

• indeximagealt: --- Add alt text to your index image. Please add alt text. It makes our website more accessible. If you see any images on this site that do not have alt text, please add some in the git repo.