search

lfe / lfe.github.io

The LFE Landing Site / Home Page
https://lfe.io/
28 stars 19 forks source link

Migrate blog.lfe.io to lfe.io/blog #105

Open oubiwann opened 3 years ago

oubiwann commented 3 years ago

This will:

Blocked by #104

Fixes https://github.com/lfe/blog/issues/29

Branch epic/105/add-blog

Tasks:

Cleanup tasks:

Old tasks:

oubiwann commented 3 years ago

So, after some deep exploration of Zola, I don't think I can easily do what I want to do with things as they are. This essentially boils down to how taxonomies are handled (e.g., "tags", "categories", "authors", etc.): the problem being that these are all processed at the top-level directory. For us, the top-level directory is the LFE site itself; the blog will sit under that. We want /blog/tags etc. not /tags.

Two possible ways forward are:

  1. Keep blog content where it currently is, published to the lfe/blog repo. The "builder" code for Zola could be anywhere (in the same repo, or in the site repo) ... but it would be nice to keep a unified set of stylings in one location ... maybe even a repo of its own?

  2. Move all the content -- builder and actual blog -- out of the current lfe/blog repo and into the lfe/lfe.github.io repo, moving the current code in the builder branch into a "site" subdir, and creating a "blog" subdir for the blog builder code. A new top-level Makefile could be created that would build both and publish them optionally together (at the same time) or separately, as needed.

I've been pondering this for about a day, and still haven't landed on a decision. Will continue to weigh and experiment ...

oubiwann commented 3 years ago

I want to rule out the approach of separate sass, site and blog repos ... but:

  1. to manage those, I would put them in a single repo as submodules, and
  2. if I don't go that route and put everything in lfe/lfe.github.io, I still might be creating a git submodule for the lfe/blog repo ...

So, there will probably be a git submodule setup, regardless. Also, if any content or builder code ends up in two or more separate repos, there will definitely be a main repo to consolidate these resources and reduce maintenance overhead and increase the chance of contributions.

Additionally, in Zola, we can't exactly duplicate the same URLs as those produced by the existing blog, though I did get them close. Witness:

Current blog:

Possible new URLs:

To get Zola to be that close took some hacking / metadata duplication that will have to be scripted with Makefile targets. But his does mean that we'll need to set up some redirects that point from the old blog.lfe.io/site URLs to whatever the new base URL will be.

These options show there's not really a clear winner in approach, thus my delay in making a decision.

oubiwann commented 3 years ago

Let's see what some competing solutions might look like:

Approach 1

All building done in one repo (lfe/lfe.github.io)

  1. The lfe.io site builder code and raw markdown is all in the top-level dir of that repo; this would have to be moved into site
  2. site would have it's own Zola build/config/etc setup
  3. We'd have to add a blog dir which would also have its own Zola build/config/etc
  4. Not wanting to duplicate css, shared images, etc., we'd want to figure that out ...
    1. maybe a make target that copies site static content into blog?
    2. and then have blog use the generated sass from site (as a static resource)
    3. while overriding that CSS with its own generated sass? Shared variables become an issue at that point ... so maybe we want to copy all of the sass dir into blog? No, making changes becomes problematic in that scenario ...
    4. we'd want for all blog content to reference the base URL for things like static content, generates CSS, etc. ... not sure how that would pan out for a local build when running just the blog portion with Zola's local HTTP server ... I mean, the base URL will be 127.0.0.1/blog/ ... so how will references to /some/thing.css be handled by the local HTTP server?
  5. A full build would be site, then blog, then combine the outputs of these two in one dir
    1. so maybe a git submodule top-level build dir that points to the master branch of lfe/lfe.github.io
    2. copy site/build/* into build/
    3. copy blog/build as build/blog
    4. commit and push build to the master branch of github, publishing the web content
  6. Replace all existing published content in the blog repo with HTML redirect files that point to the new location

Approach 2

Keep lfe.io and blog.lfe.io content and builder code separate. no git submodules

  1. Standardize on the Zola tooling, so both repos would simply use that tool and not share any code (!!)
  2. Things would basically work as they do today (though no Ruby or Jekyll, so that'd be an improvement)
  3. There would be duplication (and possible divergence) of stylings, imagery, build process, etc.
  4. There would be the overhead of different repos for what would be -- visually, anyway -- a unified web experience (breaking symmetry)

Approach 3

Keep lfe.io and blog.lfe.io content and builder code separate, but share commonalities with submodules

  1. Split out the following directories into their own repos:
    • sass
    • static
    • templates
    • syntaxes
  2. Update the lfe.io and blog.lfe.io repos to pull these in as submodules (duplicated infra setup / maintenance)
  3. There would still be duplication of build process across two repos
  4. There would still be the overhead of different repos for what would be -- visually, anyway -- a unified web experience (breaking symmetry)

Approach 4

Move all content to lfe.io, use symlinks for shared resources (variation on Approach 1)

  1. Re-org to top-level site and blog builds
  2. Share resources with symlinks (will this work with Zola? Untested ...)
  3. Everything else the same as in Approach 1?

Approach 5

Move all build code to lfe.io, use symlinks for shared resources, publish to separate repos (variation on Approach 1)

  1. Re-org to top-level site and blog builds
  2. Share resources with symlinks (will this work with Zola? Untested ...)
  3. Everything else but the combining and publish steps is the same as in Approach 1
  4. For publish step, push separate builds to master on lfe/lfe.github.io and master on lfe/blog
  5. Replace all old published content in the blog repo with HTML redirect files that point to the new locations for the content
oubiwann commented 3 years ago

I think I'm leaning toward 4 or 5.

The code that I'm working on right now can be adapted to either of these. Probably 4 would be easiest to start with, and if I land on 5 I can always to the little extra work to adapt 4 code to that needed for 5.

oubiwann commented 3 years ago

Staging is now viewable here:

oubiwann commented 8 months ago

Approach 6

Don't have the tooling bend us into pretzels; use different tooling: