
I have a few old self-hosted [WordPress](https://wordpress.org/) sites that need to be migrated off a VPS. I’m still
happy with the content and don’t want to just dump them, but I also don’t want to have to keep managing a WordPress
installation for what are now static sites.

The core requirements for my migration are:

1. Markdown support
   No more fussing with a database or headless CMS. I need flatfile.
2. URLs to match WordPress
   Some of my posts seem to get hits still and perform quite well, I don’t want to mess with the SEO or anyone’s
   bookmarks.
3. Colocated images
   One thing that drives me batty about a lot of these frameworks is the poor support for colocated images with posts.
   Why is this such a massive issue?
4. Off the shelf themes, preferably [TailwindCSS](https://tailwindcss.com/) because that’s what I’m using predominantly
   at the moment, but I’ll take anything nicely structured and easy to manage and tweak.

I’ve been using [NextJS](https://nextjs.org/) for most of my other projects, but those have more complexity, this is
just a blog. NextJS feels like overkill.

[Zola](https://www.getzola.org/) seemed like a good idea at first glance, but they don’t support permalink
customisations, and the structure is quite restrictive. The themes available are also thin on the ground and mostly
unsuitable for what I wanted.

Searches suggested [Eleventy](https://www.11ty.dev/), although there are several complaints about the challenges of
colocation of images, usability of documentation, amongst other things. I have taken a look at it before as a framework
for my other sites, but as others noted, the documentation isn’t as approachable as with other frameworks.

That said, a starter is worth a shot and there
is [this helpful guide](https://www.smashingmagazine.com/2020/12/wordpress-eleventy-static-site-generator/) by Scott
Dawson for migrating WordPress to Eleventy and deploying to [Netlify](https://netlify.com/), which is exactly what I
intended to do.

And thus, we press on. Or unWordPress on.

## Step 1. Export WordPress

Use the built in WordPress export tool to dump the entire site to xml.

## Step 2. Convert WordPress export to markdown

Thank goodness for tools
like [`wordpress-export-to-markdown`](https://github.com/lonekorean/wordpress-export-to-markdown).

Does exactly what it says on the tin. I used the options to create year, month, and individual post directories, save
the attachments and scrape for external images.

## Step 3. Set up Eleventy

The guide by Scott Dawson recommended a different starter project, but I
found [vredeburg](https://github.com/daflh/vredeburg) which incorporates TailwindCSS and looks almost the way I want for
a simple blog.

Clone it.

The theme works as is out of the box, but you can’t quite just drop in your converted posts. Will get to that shortly.

Still, you can move the converted posts in now. Copy the converted `output/posts/` into `src/posts/`. The conversion
also puts pages in date folders but they don’t need to be in that structure in Eleventy, so copy the leaf folders
in `output/pages/` into `src/`.

### Site configuration

- Update `_site/author.json` and `_site/site.js` with your own details.
- Update `menu.json` with your intended navigation items.
- Update `tailwind.config.js` to suit your tailwind theming preferences.
- Update the images in `src/assets/img`.

Easy enough.

## Step 4. Image colocation support

This is the where the bulk of the work needs to occur.

1. Install the following packages:

    ```jsx
    npm i -D markdown-it-modify-token
    ```

2. Update `eleventy.config.js`with (comments inline):

    ```jsx
    // Import this
    const modifyToken = require('markdown-it-modify-token');
    
    module.exports = function (config) {
        ...
      // Pass a custom instance of markdownIt into eleventy.
      config.setLibrary("md", markdownIt({
          // html, breaks, and linkify are default options from eleventy.
          html: true,
          breaks: true,
          linkify: true,
          // This will prepend the colocated image path with the built asset path
          modifyToken: function (token, env) {
            switch (token.type) {
              case 'image':
                // Only apply this transform to relative image paths
                // Regex explained: https://regex101.com/r/EM83AR/1
                if (token.attrObj.src.match(/^(?!www\.|(?:http|ftp)s?:\/\/|[A-Za-z]:\\|\/).*/)) {
                  // https://www.11ty.dev/docs/data-eleventy-supplied/#filepathstem
                  const stem = env.page.filePathStem.split(path.sep);
                  stem.pop();
                  token.attrObj.src = path.resolve(stem.join(path.sep), token.attrObj.src)
                }
                break;
            }
          }
        })
          .use(modifyToken)
      );
    
      // This copies your images from where they are colocated to a similarly pathed location in `dist`
      // It allows the modifyToken above and colocatedImagePath filter below to work.
        config.addPassthroughCopy('src/posts/**/images/*');
        
      // This adds a filter that performs a similar transform as modifyToken that you can use in templates
      config.addFilter('colocatedImagePath', (src, filePathStem) => {
        const stem = filePathStem.split(path.sep);
        stem.pop();
        return src ? path.resolve(stem.join(path.sep), src) : '/assets/img/no-image.svg';
      });
        ...
    };
    ```

This allows you to colocate your images and makes pointing them to the right place in `dist` build’s problem and not
yours.

You can keep using `![]()` syntax and it will ‘just work’, however, the WordPress conversion will

In the `post-grid.njk` partial or wherever you put your post loop, you can also modify the cover image tag to use
the `colocatedImagePath` filter:

```html
<img src="{{ post.data.coverImage | colocatedImagePath(post.filePathStem) }}" alt="{{ post.data.title }}" />
```

## Step 5. Update markdown files

There are a few changes you will need to make to your markdown, sorry.

1. If you use WordPress galleries, you will have to manually convert the shortcodes to markdown image syntax and map the
   asset IDs to the colocated files.
2. If WordPress uses a resized image instead of the original, you will need to remove the `-widthxheight` portion of the
   filename. You can use a regex here.
3. You will need to search for any other shortcodes to replace them with something else.
4. None of my `code` or `pre` content seems to have been converted into markdown. Those had to be found and wrapped with
   the necessary backticks.
5. I had some draft posts, apparently. These get converted
   by [`wordpress-export-to-markdown`](https://github.com/lonekorean/wordpress-export-to-markdown) without a clear
   indication that they’re draft. I didn’t want to publish them, but they were fleshed out enough that I didn’t want to
   delete them either. For each of these I added `draft: true` to the frontmatter, snaffled `eleventy.config.drafts.js`
   from [`eleventy-base-blog`](https://github.com/11ty/eleventy-base-blog) and updated `eleventy.config.js` to use it:

    ```jsx
    const pluginDrafts = require("./eleventy.config.drafts.js");
    
    module.exports = function(eleventyConfig) {
        ...
        eleventyConfig.addPlugin(pluginDrafts);
        ...
    };
    ```

## Step 6. Implement categories and tags

Eleventy uses ‘tags’ to represent the internal collections. Apparently, it’s not taxonomy the way categories and tags
are used in WordPress. To keep these separate, you can create a new collection for them.

Replace frontmatter references to `tags` with `hashtags` to give them a separate namespace. You can use a regex here.

The following gist contains the collection definitions, their paged equivalents, as well as sample index and individual
pages for each. These have been based on the existing files for posts and tags from the starter.

<Gist id="61685cfd85b0cd301ec9608610695b4c" />

## Step 7. Deployment to Netlify

This was pretty painless. Hook up Netlify to the repo and it’ll trigger a build. The `netlify.toml` that came with the
starter probably helped, but it really just took care of itself.

After that, I just had to update the DNS to point to the Netlify deployment, hook up the Lets Encrypt SSL cert through
Netlify and off it went.

---

## Additional changes

- I replaced the search box in the header with a link to `/search` because I couldn’t get the form to pass the query
  param or it otherwise lost it once it reached search page.
- Modified the footer to make the year dynamic using this helper in `eleventy.config.js`:

    ```jsx
    config.addHandlebarsHelper('currentYear', () => {
      return DateTime.format(new Date, 'yyyy');
    });
    ```

- Some of my images are smaller than the post width, so I added the following blanket fix to `assets/css/main.css`:

    ```css
    .prose img {
        @apply w-full mx-auto;
    }
    ```

If your blog is still active, there’s some other good stuff you can snaffle
from [`eleventy-base-blog`](https://github.com/11ty/eleventy-base-blog) like RSS feed support. So it’s worth poking
around that starter to see else you might find useful.

## Caveats:

This method does none of the optimisation things that [`eleventy-img`](https://www.11ty.dev/docs/plugins/image/) does
because build time took forever, I’m impatient, and I honestly don’t care so much about this right this minute. My
priority is to get the sites off before my VPS expires. If image optimisation is a priority, you should be able to
integrate `eleventy-img` possibly with `eleventy.config.images.js`
from [`eleventy-base-blog`](https://github.com/11ty/eleventy-base-blog/) as a foundation but I don’t know how compatible
that will be with the above, YMMV.

## Resources:

- [How To Migrate From WordPress To The Eleventy Static Site Generator](ty-static-site-generator/)
- [wordpress-export-to-markdown](https://github.com/lonekorean/wordpress-export-to-markdown)
- [vredeburg](https://github.com/daflh/vredeburg) Eleventy and TailwindCSS starter

How I migrated old WordPress blogs to Eleventy with colocated image support.

Migrate WordPress to Eleventy with Colocated Images

MDX on GatsbyJS nests JSX components in paragraph tags which can produce invalid HTML so you end up with invalid HTML resembling:

```html
<p>
	<div class="jsx-component">...</div>
</p>
```

When using Markdown tables, it can also leave extra whitespace that can produce HTML syntax warnings. Not showstopping, but annoying all the same.

Create this plugin in your `./plugins` directory and add it to the end of your `gatsbyRemarkPlugins` in `gatsby-config.js`.

<Gist id="c5321b66ef8afabd6f0fdf67055aabc8" />


MDX wraps components with paragraph tags and can add extra whitespace in tables which produce invalid HTML. This GatsbyJS plugin cleans up the markup.

Clean-up Extraneous Paragraph Tags and Table Whitespace in MDX on GatsbyJS

For [STEAM Powered](https://steampoweredshow.com) Facebook videos and YouTube allow you to attach an SRT file for captions. However, Twitter and Instagram do not and captions need to be baked-in.

Use this bash script create new videos with the SRT captions baked-in. The script needs to be run in the directory that contains video files with their corresponding SRT files (with the `.en_US` language suffix). New videos with the captions baked-in will be created in the same directory.

<Gist id="97e0b54ef35929bf05a3dcf1ae316ff5" />


How to create baked-in captions in videos using srt files and ffmpeg.

Bake-in SRT Captions into Videos Using ffmpeg

tl;dr: I need to generate my own SRT files for my videos because Facebook Creator Studio makes me angry.

Long: [Backstory](/rail-yard/video-captions).

## Requirements

- python
- [ffmpeg](https://www.ffmpeg.org/)
- Google Cloud API Key with the Speech to Text product enabled. ([instructions](https://cloud.google.com/speech-to-text/docs/quickstart-client-libraries))

More details for installation and usage in the script below.

## Notes

Default GCS only works for videos no longer than 60 seconds, and the script will only send the first 60 seconds of video to accommodate this. Modifications are required to use GCS for longer videos[1].

I find the `video` transcription model more accurate than the `default`, but `video` is a premium model if that matters to you. I still need to make corrections, but far fewer than Facebook's auto-captioning feature.

For bin length, I've set it to a default of 3 seconds with a line break of 37 characters[2].

```text
1
00:00:05,100 --> 00:00:07,500
Big Bang Theory thank you. So
especially in that
```

<Gist id="abbabb693f37d49ccbd9348178c5963b" />

---

[1] See [https://towardsdatascience.com/how-to-use-google-speech-to-text-api-to-transcribe-long-audio-files-1c886f4eb3e9](https://towardsdatascience.com/how-to-use-google-speech-to-text-api-to-transcribe-long-audio-files-1c886f4eb3e9)

[2] 3 seconds seems to come up a bit, and the first subtitle style-guide I found is from the [BBC](https://bbc.github.io/subtitle-guidelines/) and I saw 37 characters on there because of teletext. For online it's based on percentage of screen-width and at that point I realised close enough is good enough. Got better numbers? Let me know.


Using Google Cloud Services Speech to Text to generate SRT files from short videos.

Generate SRT files with Google Cloud Services

Here's an example migration for automatically creating permissions on groups.

This specific install uses both `allauth` and `guardian` which is reflected in the migration dependencies, but as this uses Django core `Group` and `Permission` objects, it should work without those two modules.

As noted in the gist, YMMV.

<Gist id="6a8ac71539220b1f13a95bd559f2c4bd" />


How to create permissions on groups in Django in a migration.

Create Group Permissions with Migrations in Django


I use markers in DaVinci Resolve to annotate videos for show notes and navigation links in YouTube video descriptions.

![YouTube timeline](timeline.png)

To output the marker info as an EDL, activate the timeline whose markers you want to output, then in the **Media** tab, right-click on the timeline, select **Timelines** &rarr; **Export** &rarr; **Timeline Markers to EDL...** and save the EDL file.

<Callout type="warning" icon="⚠️">

If the timeline isn't open, the <strong>Timeline Markers to EDL</strong> menu item will not be available.

</Callout>

![DaVinci Resolve Screenshot](screenshot.png)

Then, use the following python script to output the marker info in the format:

```text
[00:00:00] Marker name
```

<Gist id="fe15ae724b1cc92bb88f7b6c7e5ac274" />


Use DaVinci Resolve marker EDLs to create timelines that can be used in show notes and YouTube timelines.

6 posts tagged “gist”

Migrate WordPress to Eleventy with Colocated Images

Clean-up Extraneous Paragraph Tags and Table Whitespace in MDX on GatsbyJS

Bake-in SRT Captions into Videos Using ffmpeg

Generate SRT files with Google Cloud Services

Create Group Permissions with Migrations in Django

Convert DaVinci Resolve Markers to YouTube Compatible Timelines