Day 12

In sharp contrast to yesterday’s total lack of an update, tonight we have two really awesome new features.

Let’s dive in:

Weblog.lol API

The first version of the Weblog API is ready for testing. You can read up on it here, but the quick summary is that there are three endpoints:

Create a new weblog post
Rebuild a weblog
Delete a weblog post

They’re mostly stable, but have only been very lightly tested so far, so please report any issues.

OK, cool, but what fun is an API without something that uses it? Enter our second feature...

Weblog.lol GitHub Action

Last night, Dave Winer posted this:

I wholeheartedly agree. And so as far as weblog.lol is concerned, this new feature opens up an entire new world of editing possibilities thanks to the new API and GitHub Actions. You can use any editor you like (or at least any that integrates with git repositories, which includes many of them) and start using your own workflow for publishing your weblog posts.

☠️ First, a warning: This process introduces a new destructive process and must be used with extreme caution.

Hate to be so dramatic about this, but data loss is serious business. If you don’t already have a backup of your weblog posts, please make one now. You can generate an export right from the omg.lol weblog UI, so there’s no excuse not to have a backup on hand.

So, here’s the deal behind this feature: you can now set up a GitHub repo, store your posts there, and publish directly to weblog.lol through a GitHub Action. It works pretty well so far (but, again, and as with everything here — it’s extremely ultra alpha software).

The key gotcha here is that this is a one-way deal: when you run the GitHub Action, everything you have in weblog.lol is deleted and replaced with what you pushed to your repo. That’s really important to remember (and is the basis for the scary warning above). Also, consistent with the current one-way approach, any edits you make in the web UI after a repo push will not be synced with your repo, and will be overwritten with a subsequent repo push. Not great, I know, but we’re definitely at a “crawl” stage with this setup and the full bi-directional syncing is somewhere between “walk” and “run”. We’ll get there eventually!

Here are the steps to get started:

First, create a new GitHub repo.
Add the file .github/workflows/main.yml with this content in it:

on: [push]

jobs:
  weblog_import:
    runs-on: ubuntu-latest
    name: weblog.lol
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 2
      - id: weblog_import
        uses: neatnik/weblog.lol@v1
        env:
          ADDRESS: your-address-here
          WEBLOG_API_KEY: ${{ secrets.WEBLOG_API_KEY }}

Change the your-address-here bit above to your own address.
In your repo settings, click Secrets, and then Actions. Click New repository secret, and add the following:

Name: WEBLOG_API_KEY
Secret: your omg.lol API key (you can find this on home.omg.lol/account, at the very bottom)

Add a folder to your repo called weblog.
In the weblog folder, you can add all of your weblog pages and posts. But, just like with Gremlins (a classic holiday film), there are three rules you need to follow:

Rule number 1: Only files with a .md extension will be processed.
Rule number 2: You can’t have any posts inside of the root of your weblog folder. Why? Because there’s a bug that I haven’t yet fixed. So, please put them in a folder like posts or 2022 or whatever you’d like. You can store your static pages in a folder called pages. You can actually put anything anywhere—just not in the root folder.
Rule number 3: Your folder structure within the weblog folder has no bearing on how your posts are managed or published. All other settings that have governed post URLs continue to work as they have over the past 12 days; things like your configured post path and post metadata (path, slug, location, etc.) will continue to dictate the URL where posts are accessed.

With eveything configured above, you can commit your stuff and push it into the repo. That will trigger the action, and then you can watch the action run. Click Actions at the top of your repo screen, then click on the running job, and then click on the weblog.lol job on the left under Jobs. Then expand the Run neatnik/weblog.lol@v1 item to see the status of the job.

This is all highly experimental, so please let me know if you run into any issues with any of it.

That’s all for now. As always, keep the bug reports flowing (GitHub issues are always helpful). See you again tomorrow, behind yet another door.

— Adam