1. Static files manually edited over FTP
2. Dynamic files edited over FTP
3. Markdown/DB + dynamic files
4. Custom CMSs in source control
5. Browser wars + Javascript
6. Frameworks
7. Mobile
8. Dependency management
9. Headless + lean artisinal stacks
10. Visual Editors + live preview
11. Collaborative cloud stack
12. AI generated, who cares

Am I missing something?

Should I try to put approx years on it?

How to start a nerd war:
“Should UI tokens be documents?”

VERSION TWO

Code should clearly state its purpose. For best results, it should guide contributors with basic principles. Values differ within an application stack and need to be clarified. These are for the frontend, some may be relevant elsewhere. Feedback welcome.

Delightful Dev Experience

1. prioritize readability, clarity, approachability, and assume you’ll forget
   
2. provide instant-feedback workflow for components and variations
3. nest coupled code together, extract and elevate reusable bits
4. keep builds fast and reliable, enable frequent testing
   
5. borrow repo norms, format and lint on save
   

Delightful User Experience

1. provide instant interaction feedback
2. don’t distract or context switch
3. be minimal, fine-tune visual weight
4. track end-user interactions including errors/warnings
   

Stay Isolated

1. create reusable, decoupled elements
2. use static mock data (at least for initial state)
3. minimize external services, register/identify when you do

Use Existing Tools

1. avoid re-building commodity features, unless core to your point
2. inherit and collaborate on types and API interfaces
   
3. leverage existing code and frameworks, or delete it
4. keep automation simple and empowering

Make it Flexible

1. easily adaptable has more actual value than barely working
2. think configuration first
   
3. allow design choices to be easily propagated
4. be a data model stakeholder

Work Incrementally

1. ship unimplemented code early while fresh
2. expose your work to colleagues
3. test ideas in chunks, get data, follow the truth

Is @eleven_ty the new @metalsmithio?

TLDR; This post highlights a stack of useful plugins to rapidly assemble a static site generator that’s powerful and easy to program… even though the core tool has stopped growing.

I needed to pick a static site framework about two years ago and I chose Metalsmith. It’s a lovely, minimal, open-source tool… however since summer of 2018 there hasn’t been any substantive work. Segment officially handed it off. Scamper to the next shiny thing right!? 🐿

I manage a medium-sized (mostly marketing) website for my day job and rely on Metalsmith along with community plugins and still enjoy it. I’m not held back, it’s simple to adjust, and a huge library of plugins have aligned on sensible norms. 🙌🏻 The architecture makes it very simple to add your own custom plugins and adjust data on it’s way to be rendered.

What Is Metalsmith?

First, here are some useful quick links about the platform and plugins:

• Official plugin list
• Less official, bigger plugin list
• List of resources
• Slack channel
• Frontmatter explanation

What Do These Plugins Do?

These plugins construct a pipeline to render a site without boilerplate or complexity. Of course, the point of such architecture is to conform to your specific needs… but it never hurts to peek at someone else’s core blueprint. 

• Most content should be editable in a CMS, pull it from Prismic.
• Data from APIs needs to be available to templates/pages/layers.
  
• One-off pages can be hard-coded markdown/YAML.

Essential Plugins

• Assemble Components and Pages
• metalsmith-layouts - page level templates
• metalsmith-discover-partials - expose partials/includes
• metalsmith-in-place - use data and partials in markdown
  
• metalsmith-collections - organize grouped pages
  
• Expose Content Beyond Markdown Files
• metalsmith-json-to-files - convert JSON into pages
• metalsmith-data - expose JSON data to templates
• metalsmith-prismic-server - content via Prismic CMS
  
• Handy Utilities
• metalsmith-permalinks - easy file named urls
• metalsmith-alias - simple HTML aliases
• metalsmith-fingerprint - hash filenames for cache busting
• metalsmith-i18n - simple internationalization
• metalsmith-sitemap - generate a dynamic xml sitemap

Build Tasks

There are Metalsmith plugins for common build tasks like: SASS compile, JS concat/minify, etc. I recommend not using them and doing this stuff with a build tool like: Gulp, Grunt, Webpack, etc. That’s what it’s for. You’ll probably need a build step to download and transform API data and reload the browser when done anyway. Use Metalsmith as a site generator, that’s what it’s for.

I hope this is helpful!

TLDR; I’m updating an existing medium-sized static marketing website to be mostly editable.  The fastest route is using a SaaS CMS and a static rendering framework. I chose Prismic. I discuss API CMS services in this post.

UPDATE: 4 years later, I chose Sanity.io

Constraints and purpose…

BACKGROUND: I’ve been building content-focused websites with CMSs professionally for a long time (10+ years).  One critical piece of good architecture is appropriate de-coupling of content admin/storage/config/schema from the end-user style/theme/UI.  Failing to do so is an engineering anti-pattern resulting in a monolithic codebase.  System layers should not know too much about each other, this is important for testing and sanity as a team grows.  For me, creating separation has ranged from backend-agnostic front-end skins, website agnostic themes, to fully headless front-end apps consuming content APIs (for both static pre-rendering or client-side rendering).

RANT: However— when starting fresh for marketing purposes, I would never create a totally decoupled front-end from the content storage/schema.  It means duplicate work, re-inventing the wheel, and creates too much reliance on developers for site enhancements.  Marketing sites are not ground-breaking evolving products, most of their feature needs are known.  Most CMS content admin features and web UI features are mature commodities.  You should be able to assemble pages, build and author content, and create experiences without writing code (or at least not much).  What’s usually unknown (in the marketing world) is the content structure, which needs to change and grow without writing code to try it out.  Enabling content velocity is the goal, not developer flexibility for building new features.  Pardon the rant.

Yet, I’m working with a site (styles/pages) that already exists and just needs to rapidly enable editability piece-by-piece to bring value immediately.  So I must dive into the world of SAAS CMSs in order to serve content via API within days.  Theming a real CMS to match existing style takes weeks.  Allowing non-devs to control content is a worthy goal with real value, even though the result isn’t how I’d start an end-to-end solution.

CMS frameworks…

So what frameworks are the contenders to make a medium-sized marketing site editable for a small team of brilliant folks?  I’m only considering an entirely SAAS hosted CMS with a focus on API content serving.  There are two sides of this puzzle: back-end CMS, and front-end templating/rendering.  This post is about content storage/serving.  I’ve included links for each service relevant to building mid-sized marketing sites, others are available.  Discussing pros/cons of rendering systems is an opinion minefield, pick a CMS that works with what you like and know well :)

Prismic

This service was suggested to me and seems to be a leader.  Testing out the workflow revealed a clean/simple UI (for CMS pros).  Creating content types and schema is rather easy, as is editing content once it’s built.  They allow reference fields, so hierarchy and other relationships seem plausible.  It allows content entities to be described in code as well, which could allow some front-end schema sharing.  They even have the concept of flexible horizontal page sections, called “slices” …not a good name.  The query structure seems sensible and they have an exploration UI for building them, but I didn’t go too deep.  They have a concept of previewing content changes, but it makes a lot of assumptions.  I was impressed by their integrated A/B experiment feature, which requires setup on the rendering end, but is easy for authors to create content variation.

• Cost: wide-range of plans from super cheap to enterprise with SLAs
• Render: jekyll, react, metalsmith, laravel symfony, more

Storyblok

The schema creation process is a bit convoluted with Storyblok.  It’s flexible and thought-through, just not immediately intuitive.  The UI is certainly tidy, but you have to wrap your head around their concept of components and blocks that get attached to one common story object… vs building various entity types.  This enables assembling pages from predefined components.  The authoring experience is just not great for non-technical people, meaning it seems difficult to just create a page and write some text content… but who does that?  Several clues make me think this framework is intended mostly for commerce scenarios.  Their most interesting feature is their “rendering service” (via Liquid templates).  If you use this their preview mechanism within the editing workflow would be very easy to have managed for you.

• Cost: wide range of plans, enterprise via contact form
  
• Render: liquid, express, vue php-client, more
  

Elemeno

The admin UI was extremely easy to use both for building the schema and adding content.  There were a few hiccups with forgetful forms and a less full set of field types, but everything was easy.  They also have references and multi-value field groups, which should enable complex structure if necessary.  Their API looks sensible, however, their docs are somewhat light, which matches this simple straight-forward tool.  A lack of SDKs or code examples make this the baby in the bunch… but nice and lightweight.

• Cost: all plans are cheap
• Render: github.com/elemenohq

Contentful

This service appears to be the most mature and has had time to care for the experience of devs, admins, and authors.  Small features like easier to set up field validation, multi-value fields, and field-level localization show off its robustness.  (Field-level multi-lingual is the right way to do it.)  One strange oversight was the inability to control what types a reference field can link to.  Their developer docs are very thorough for many languages, and SDKs are readily available.  They’ve chosen SDKs rather than targeting popular frameworks, though some examples exist.  They also have a decent amount of integrations.  All of this makes sense since they are the most expensive option in this comparison.

• Cost: starts-off kinda expensive, the free plan requires a logo (lame).
• Render: jekyll, js sdk, angular, symfony ex, laravel ex, more

Common notes

Native tagging systems were super flat/simple and shared across everything, I would probably only use that for admin organization and stick to list fields or reference fields for real categories.

Multi-lingual was generally offered at the page/document level, rather than field-level.  This doesn’t matter until you get pretty deep into translation, but that might matter to you.

Content modeling via an admin UI was available everywhere.  I was happily surprised to see it …as someone who’s relied on open-source tools for modeling for a long time.  However, they are locked into a limited set of tools managed by them (compared to hosting a CMS).  You’ll need to rely on editor smarts and handling things on the render side.

Most services offer webhooks to rebuild/deploy or clear cache on your site.  You will need to set that up and beware of changes to your master branch depending on your comfort with continuous integration.

All services offer basic content versioning, several include scheduling or grouping content together for releases.  Be sure to check on this if it matters to you.

Others services…

The services I reviewed are not the end of the story.  There are others worth your time to check out to find the best solution for you, here are a few…

• Sanity - customizable editor, deployable schema
• Ghost - open source and includes rendering
  
• Forestry - includes hosted build deploy steps
• Kentico Cloud - includes workflows and personalization
• WebPop - includes a cloud IDE for templates
• Osmek - prebuilt content bins (types)
• DatoCMS - tag hierarchy and a search API