DEV Community: Stackbit

The Challenges Marketers and Developers Face in the Era of Headless CMS

TiffinTech — Thu, 27 Apr 2023 16:54:09 +0000

While headless CMS has proven its efficiency, flexibility, and speed, it also comes with its own set of challenges for both marketers and developers. In this article, I will outline three key points that outline these challenges and provide insights on how to overcome them.

1. Bridging the Gap Between Content and Presentation

One of the core benefits of a headless CMS is its separation of content from presentation. This allows developers and marketers to work on the same platform without any constraints on the creative process. However, this separation also creates friction, as marketers are often less technically inclined and may struggle to visualize the final outcome of their content.

To overcome this challenge, it is essential to have a strong collaboration between the marketing and development teams. Providing a user-friendly interface for marketers to preview their content in real-time can bridge this gap, making it easier for them to understand how their work will appear in the final product. This can be achieved by using a tool such as Stackbit that provides marketers with a visual editor and enables developers to work with their preferred tech stack.

2. Managing Workflows in a Decoupled Environment

In a traditional CMS, developers and marketers often rely on the same system to manage their workflows. However, with a headless CMS, these workflows become decoupled, which may lead to a lack of visibility and coordination between teams.

To address this issue, it is important to establish clear communication channels and create a well-defined workflow. Utilizing project management tools and platforms like Trello, Asana, or Slack can help teams stay on the same page and track progress more effectively. By defining roles, responsibilities, and deadlines, marketers and developers can work more cohesively, leading to a smoother content production process.

3. Balancing Flexibility and Security

Headless CMS offers unparalleled flexibility in terms of content delivery, enabling developers to use various front-end frameworks and technologies. While this flexibility is a significant advantage, it can also lead to potential security vulnerabilities as content is served through APIs.

To ensure the security of their content, developers must be vigilant about their choice of APIs and frameworks. By implementing best practices such as securing API keys, using authentication and authorization protocols, and monitoring access logs, developers can minimize potential risks. Additionally, staying informed about the latest security trends and updates in the industry will ensure that the content management system remains protected from new threats.

Conclusion

While headless CMS presents new challenges for marketers and developers, these can be effectively addressed with clear communication, well-defined workflows, and a focus on security. By embracing these strategies, teams can successfully navigate the friction that arises from working in a headless CMS environment and unlock the full potential of this innovative content management approach.

Here is a full video discussion to learn more about the challenges marketers and developers face while working with a headless CMS.

How To Enhance Your Web Development Process with Stackbit and Storybook

TiffinTech — Thu, 06 Apr 2023 18:58:05 +0000

Ensure that you have installed Stackbit. Stackbit is a visual editor that enables content editors to build pages and update content directly on the site, without having to rely on developers. Allowing developers to focus on building features and working on larger tasks. Follow this step-by-step guide for how to simply add in Stackbit locally to a project.
Install the stackbit/storybook-addonfor Storybook. This plugin will allow you to create Stackbit models and presets based on your existing components and stories. These generated models can serve as a starting point for setting up model definitions and presets in a new project.
Once the add-on is installed, return to your Storybook project. You should now see a Stackbit tab that will allow you to generate new models based on your components and stories.

4.Click on the Stackbit tab and follow the prompts to download your newly generated models. These models can then be used to set up Stackbit content editing within your Storybook project.

By following these simple steps, you can easily set up Stackbit with Storybook, providing your content editors with the ability to update site content without developer intervention, while simultaneously enabling your developers to build more efficiently.

Here is a video diving deep into each step using a Next.js project. Enjoy!

3 Creative VS Code Extensions You Need To Try Out

TiffinTech — Tue, 28 Mar 2023 19:26:48 +0000

Polacode

Polacode is an incredible Visual Studio Code extension that makes it easy for developers to create stunning screenshots of their code. With Polacode, users can quickly and accurately select the code they want to capture and generate a high-quality image. And it doesn't stop there; they can also take advantage of the several customization options available such as changing the font size and background color, or adding a caption to their image.

One of the most notable aspects of Polacode is its ability to capture code with syntax highlighting retained, making it ideal for tutorials, presentations, or any other scenario where code readability is important. Furthermore, Polacode is open source and actively maintained by its development team, so users can rest assured knowing new updates and bug fixes are regularly released.

In short, Polacode is an excellent resource for developers who need to create visually appealing code screenshots for documentation, tutorials or social media platforms.

Better Comments

The Better Comments extension for VS Code is an incredibly useful tool that can make it much easier to understand and organize code comments. It does this by introducing a set of special annotations that can be used to provide more context and structure to code comments, making them more readable and providing greater clarity as to their purpose.

For example, the software allows users to assign different colors to comments based on the keyword they begin with. This allows developers to quickly differentiate between comments intended for tasks that need to be completed in the future (such as those beginning with "TODO"), and those containing important information or advice (beginning with "NOTE"). In addition, visual separators such as asterisks or equal signs can be added between different categories of comments, helping to further organize each section of code.

Beyond this, Better Comments includes a number of other annotation keywords which can be used to add additional meaning and context to code comments. For instance, the “HIGHLIGHT” keyword can be used to draw attention to an important piece of code, while “QUESTION” may be used when asking a direct question within the comment. Ultimately this allows developers to communicate more effectively with their peers by creating more detailed, informative commentary on their work.

Peacock

The VS Code extension Peacock is a great tool for streamlining workflow and visually organizing the workspace. With this powerful extension, developers can easily distinguish between different projects, instances of VS Code, or other related work.

Peacock has the ability to generate unique colors for each project or allow users to set their own custom colors. This feature simplifies the process of telling apart multiple projects running at once and saves time from having to manually switch between them. Additionally, Peacock integrates with popular VS Code themes so that users can quickly create a unified color scheme across the entire IDE.

Moreover, Peacock offers a high degree of customization, allowing developers to adjust individual components like the status bar, title bar and activity bar according to their needs. This makes it possible to develop a personalized workspace tailored specifically to one's workflow and preferences. All in all, this convenient extension provides an easy way for developers to gain more control over their environment and improve productivity.

Want to see some more cool VS Code extensions? Check out the video we created diving into these and more.

How Dan & Bob (and a Company You've Never Heard of) Changed Computers Forever

Ryland @ Stackbit — Tue, 09 Nov 2021 21:53:04 +0000

You’ve never heard of Dan or Bob.

But you should have.

They built a company, VisiCalc, that led to Apple's first big success and changed computers forever.

Here’s their story.

The year is 1976

And Dan Bricklin is walking into class at Harvard Business School

He sees a dozen chalkboards connected by one massive matrix of rows and columns. With a calculator, you could change one cell and ripple thru all the connected cells.

This made Dan think:

A few years later, Dan built the first version of VisiCalc

It took 1 week.

It didn’t scroll. The decimals weren’t fixed. But it solved one huge problem—it lettered the columns and numbered the rows, so you could refer to each cell

Heres a photo of it from Dan’s old 35mm camera

Dan was ecstatic. But he hit his programming limits. So he recruited his buddy Bob Frankston from MIT

Bob went to work in the attic of this house. He used a shared MIT system that was expensive to use during prime daytime hours.

So Bob slept during the day. And worked at night.

Bob hit one huge problem.

He couldn't condense his 20KB VisiCalc code in the 16KB of the low-end Apple II.

So when it shipped it was only available on the much more expensive 32KB Apple II. They were nervous it wouldn't sell.

(Here’s some of Bob's first source code.)

Before launch, Dan sneakily used it for a class assignment.

The teacher told his class to analyze a Pepsi marketing campaign.

The next day Dan came back with 5-year projections, testing all sorts of possibilities.

When asked how he did it, he said "multiplication and addition"

Dan and Bob debuted VisiCalc – the very first computer spreadsheet – at a computer expo in Manhattan.

It wasn’t well received.

Only 22 people showed up. Of which 20 were friends and family.

The 2 “real” attendees walked out early to see the TI 59 Calculator presentation. lol

In late 1979, Dan and Bob sold their first unit for $100.

And it became a huge hit.

News stories spoke about business folks lining up to buy VisiCalc and then, the next day, lining up again to buy the $2,500 Apple II when they realized it was the only computer it could run on.

4 yrs later, Dan & Bob had sold >1M copies.

It sold so well with the Apple II that Steve Jobs claimed VisiCalc the biggest single event that led to Apple’s success.

"If VisiCalc had been written for some other computer, you'd be interviewing somebody else right now" -Steve Jobs

Beyond all the success, Dan and Bob’s work convinced people that computers are not just toys.

They are tools.

And for that, we should know who they are and give them our thanks.

If you liked this story, I share more like it 1-2 times every week on Twitter here. Cheers!

5 CSS shortcuts

Ryland @ Stackbit — Tue, 09 Nov 2021 14:47:55 +0000

It's amazing how long I didn't know about these. They make my style sheets much more clean.

I hope they do the same for yours. :-)

1/ List properties, made simpler:

2/ The background property, made easier:

3/ Font and line-height properties, made like a pro:

4/ Margin and padding properties, made how they should be:

5/ Border property, made with love:

An alternative way of looking at your career as a developer

Ryland @ Stackbit — Wed, 03 Nov 2021 18:26:48 +0000

The computer scientist, Bret Victor, empowers people to think the unthinkable.

He’s become famous for it. And he’s done it with an approach to his career (and life) that’s not normal.

I’ll explain Bret’s approach.

Bret is fascinated by ideas.

He believes great ideas in the form of art, story & invention give meaning to people’s lives.

Hence, bringing ideas into the world is one of the most important things people do.

So he asks: What tools create a healthy environment for ideas to grow?

Let’s take coding. Here’s how a normal code environment works:

Your time is spent working in the code blindly.

To better nurture ideas, Bret invented a different coding environment.

Here Bret's coding environment, next to this picture:

Say you add code for the sky and sun.

That's become Bret’s principle:

“Creators need an immediate connection to what they create.”

Meaning if you make a change, you see the effect immediately.

When he notices that principle is violated, he takes it as his responsibility to fix it.

Here's another example.

In this game, we want the little guy to bounce through the
little passageway.

He built in immediate controls of space and time.

So Bret has this principle — that creators need an immediate connection.

When he notices it being violated. He builds tools to right that wrong.

But why is this important?

As a technologist, you can recognize a wrong in the world. And you can have a vision of what a better world could be.

You can dedicate yourself to fighting for that principle. Social activists typically fight by organizing. But you, you can fight by inventing.

The takeaway is that this lifestyle is an option that’s available to you. And it’s one you’re not going to hear much about.

You can choose to sleepwalk through life and accept the tech world defining you by a skill. But you don't have to.

If there’s something in the world you feel is a wrong. Then you can have a vision for what a better world could be. And you can find your principle

So after this, think about what matters to you. What you believe in. What you might fight for

Decide to define your life your way.

If you’d posts like this on your twitter feed, follow @stackbit on twitter.

7 design principles for developers

Ryland @ Stackbit — Wed, 13 Oct 2021 15:01:21 +0000

Ever said this? And then have that happen?

Yeah, me too. lol

Here are 7 tips to help.

1/ Use Relative Units & Percentage Widths

Using em, rem, and percentages helps your CSS styles flow across screen sizes.

ex: If you need to change a breakpoint, your widths work across the board. And your font-sizes can change by simply changing the element's font-size.

2/ Content (not device width) determines breakpoints

You don't want to end up in this loop: New device, new media queries, new device, new media query...

To keep that from happening, here's what you do:

Base your breakpoints on the natural qualities of your content. As screen size increases, pick where it’d be better in a new formation

Boom! Breakpoint.

3/ Use min-width media queries

Using min-width ensures that mobile styles get loaded without desktop styles mixed in.

This can significantly improve the mobile experience and your site's SEO.

4/ Start by listing features, not designing layout.

If you’re building a cheap flights site don’t ask: “Should this item be on the left or right?”

Instead ask: “What will our users need?”

Write out items like a datepicker, input field, search button, etc. Then piece them together.

5/ Follow the thumb rule

75% of people use their thumb to operate their mobile device. Place key actions where it's easily accessible.

💚: Easy access = Most important elements
💛: A small reach = Secondary elements
🧡: Takes effort = User always notices

6/ Sketch, Design, Code.

Sketch first, always. Notice how the sketch is rough and details are left out. It gives room for interpretation on a design tool.

But it’s also specific. It’s very clear how it works, what needs to be built, and what doesn’t need to be built.

7/ LT Browser

The LT Browser was made specifically for testing website responsiveness.

✅ +45 screen sizes to test on
✅ Built-in dev tools for debugging
✅ Network throttling testing
✅ Local testing
✅ Google Lighthouse performance reports

How am I hearing about this now!?

Big thank you to the folks quoted here.

Luke Wroblewski: Mobile First Book
@adamwathan Steve Schoger: RefactoringUI
@chriscoyier: CSS Tricks
@dhh, @jasonfried: Shape Up Book

And that's it!

If you found this helpful, let me know by liking the tweet thread on Twitter. 💖🙏

7 Ways to Escape CSS Hell

Ryland @ Stackbit — Tue, 12 Oct 2021 00:23:51 +0000

Ever have this happen? lol

Yeah, me too.

Here are the 7 ways to completely center whatever you want with CSS.

`1. text-align: center;`

This works only on display: inline & display: inline-block elements. Note also that it must be applied to the parent element.

`2. margin: 0 auto;`

This works only on display: block elements. And the element must have a width.

You can also specify just margin-left: auto and margin-right: auto if you want margins on the top or bottom.

`3. vertical-align: middle;`

This works only on display: inline & display: inline-block elements.

`4. float: center;`

lol (You cannot center floated elements.)

`5. Centering absolute`

When this comes up, use transform and 50% coordinates to center an absolutely positioned element.

`6. Centering with flexbox`

Flexbox has a bunch of different alignment classes that are always applied to the parent. This here will be completely centered within the box.

`7. the one I forgot ;-)`

Jamstack Setups: The good, the bad, the ugly.

Ryland @ Stackbit — Mon, 11 Oct 2021 19:00:49 +0000

A Guide on Transforming an Idea into a Website

Sean C Davis — Thu, 09 Sep 2021 18:42:32 +0000

At its core, Jamstack was a revolution. It took the best part of the first 25+ years of website development and combined them into a powerful pattern that is used widely today. It has created an explosion of ideas and innovations that have helped developers across the world build websites that are more performant, more secure, less expensive, easier to scale, and (most importantly) fun to build!

Instead of taking you on a theoretical journey and digging into the technical nuances of the Jamstack, we're going someplace else. We'll take a more tangible journey, as we step through the entire process of building a Jamstack website, from the little light bulb in your brain all the way to a physical website that real people can visit.

These are the stops we'll make along the way:

Bring the design to life
Find a developer
Build the site (write the code)
Review and test the site
Deploy, edit, and repeat, repeat, repeat
Or ... do it the Stackbit way!

Buckle up. Here we go!

Stop #1: Design

The first stop on the Jamstack journey is design — the process of visually representing your ideas.

From Spec to Delivery

The way this typically works is that you provide some form of spec to a designer. The designer then takes that spec and turns it into one or more design files that show what should be built. That can include page layouts, individual components, or global patterns like colors, fonts, and typography.

Delivering a Good Spec

The “spec” you provide the designer should be more then, “I need a website.” Before you bring a designer into your project, consider spending time to gather the following:

A list of pages on the site, along with the purpose of each page. Bonus points if you also include content, as you'll reduce the variability of the design when it is transformed into code.
Brand assets or other visual specifications you have — logos, colors, typography, etc.
A list of websites that you really like and why you like them. The designer will want you to be happy, and the more you can tell them what you like, the higher the chance that they will deliver on your vision.
A list of competitors. Even if the designer doesn't use inspiration from your competitors' sites, it's nice for them to know where the competition stands and what it'll take to be noticed in the crowd.

The designer may ask you for more information, but this is a good start to get the conversation rolling.

Locating the Right Designer

If you have a designer already working with you, that's a bonus! If not, the cost and abilities of designers vary widely. You could use a service like Fiverr and have a decent-sized website designed for a few hundred dollars (USD). Or you could hire a fancy agency and spend tens of thousands of dollars.

Generally speaking, cost tends to be somewhat proportional to experience and the quality you're going to get back. But that doesn't mean the inexpensive designer is going to provide an awful design. This is how I usually think about it:

If I hire a designer on the cheap, I'm going to have to do more work if I want to get something worthwhile out of it. I'll have to drive the process. I'll have to deliver a super tight spec so that they give me exactly what I'm looking for.
If I hire a fancy and expensive firm, I should expect to still have to put in time and effort, but should be led through the process and be left with something truly great.

Looking Toward Development

What's interesting about this process is that while design tends to be a fraction of the cost of development, it's also largely responsible for determining the complexity of the build. Granted, a developer can spend your money in a silly way and over-engineer a website for you. But, most of the time, the time a developer is going to spend building your site is determined by their specification — the design files.

The more interactive the design, the more it's going to cost to develop. The more unique each page is from the others, the more it's going to cost to develop.

You don't have to be a fortune teller. Instead, leave a little room in your budget for going back to the designer after consulting with your developer. If the developer says you can save a thousand dollars by changing a feature, maybe you'd want to spend another hundred to have the designer reimagine and simplify it.

The Deliverable

After going through the design phase, you're left with the deliverables — artifacts you can pass on to the developer as their specification. Here's an example for a simple site that includes just four files:

Home page for large screens
Home page for small screens
Interior pages
Style tiles (i.e. global style definitions)

And this is an example of what a style tiles spec might look like:

(This example is from Unmute, a side project I'm involved with.)

Stops #2-4: Development

Toot toot! This train keeps on rolling. The next several steps encompass the development phase of the project. Our Jamstack train makes three stops here because there are usually three steps in this process, though the amount to which you are involved in each will vary depending on the developer you hire.

The Process

This process itself is similar to the design process in that it goes through these steps:

Locate & Estimate: Developer provides estimate based on specification.
Build: Developer builds the site.
Review: The developer delivers the code and you review to make sure it works.

Locate a Developer

You can go through much the same process as you did with design. If you have an in-house developer, great! If not, you can use a service like Fiverr and hire devs on the cheap. Or you can look to a more formal agency or dev shop to suit your needs.

In this case, you don't have to build a spec for the developer. You already did that! The design files are your specification.

Finding the right developer is crucial to this process, as well. And that's why I've broken out the build portion (below) as three steps. Some developers (usually those you hire on the cheap) may only complete the first step in the process. But for you to truly achieve a useful and powerful Jamstack site, you'll want someone who can take you through all three.

The Build

These are the steps in the process:

Static build
Templatizing the code
Separating content from presentation

You can spend very little on web development and still get something that you can deploy out of it. Often, that means the developer only went through the first step and gave you static files. That's totally fine, but it will make adding new pages or editing existing content super difficult.

The second step — templatizing — aims to take the static code and turn it into modular pieces that can be reused. This process is explained in great length and technical detail in this guide.

After the code has been modularized, it can be further adjusted to extract all the content and put it in a single place, such as a content management system. This process is explained in great length in this guide.

And the end of these three steps, you'll be left with a system that you can use to edit content without worrying about messing up the code. In fact, you ought to be able to edit the content without even seeing the code.

Reviewing the Site

While the review process for design was more conceptual, with development, it's up to you to actually test that the website behaves as you'd expect. In other words, you're trying to break it. The developer should respond by fixing any bugs discovered within a certain timeframe.

While the developer may not deploy the code for you, they ought to be able to help you get it running so that you can test and send notes back to them.

Stop #5: Deploy & Use!

At this point you have a site that is ready to go to production, so that's the next step. I recommend using that same developer to help you through that process, but I've broken it out here because it tends to require more effort from you than the development phase of the project.

Here are a few of the crucial steps in this process:

Choose a host and setup an account
Buy and/or configure a domain name
Add analytics tooling
Add SEO content
Use it!

Let's look at each of these briefly.

Hosting

The term "Jamstack" was coined by a startup called Netlify. And they continue to lead the way in terms of deploying and hosting Jamstack websites. But there are other great tools out there, like Vercel, GitHub Pages, Azure Static Web Apps, and many more.

Whatever you choose, you'll want to set up an account for yourself. Most of these services have a free (or low cost) tier that is enough to accommodate small websites.

Once you have an account, you can add your developer, and they will hook it up so that the code is deployed. And then you will have a working website!

Domain

You'll want a domain name for your site, otherwise you'll be left with default names from your hosting provider. If you already have one, that's great!

Your developer can tell you what you need to do to point the domain to your host, and then you'll be able to use your domain name to access your new website!

Analytics

Analytics is a crucial piece of the puzzle, because you want to know who is visiting your website. Some hosting providers (like Netlify) offer what they call server-side analytics, which tend to be the most accurate, though there are limitations to them. But if you're just getting started, it's easy enough to start with Google Analytics.

Tell your developer you want to install Google Analytics and they can help you through that process.

SEO

Of all these pre-launch steps, perhaps the trickiest to deal with is SEO. Usually I'd expect a developer to prepare my site to support SEO. That means automatically generating a sitemap file and providing the ability to customize SEO meta values for any given page. (It would be worthwhile to mention this when first setting up the arrangement with the developer so that they are prepared.)

You'll want to:

Register your site (and sitemap) with Google Search Console. This will help provide you with analytics on where you land in search results. It'll also help Google know where your site is and what its pages are.
Add custom SEO values for every page on your site, including adding an image.

If you don't feel confident in this step, you can also hire an SEO expert to help you through the process. These types of consultants also have a huge price range, from Fiverr to big agency. If you're just getting started, I recommend toward the cheaper option — just have someone give you a quick audit and make the changes they suggest.

(Insider secret: Mostly what these SEO pros are doing is using some expensive tool, hooking up your site, running a report, and giving you the output of that report. The funny thing is, some of the people are often less expensive than buying the tools and doing the work yourself.)

Editing

When all of those last bits are in place, you should have a live site and it's time to start promoting it and keeping it up to date. Make a few changes to the content. Tell the world about it. and give yourself a pat on the back.

BUT WAIT! Before we wrap this up, I want to spend a little time giving you what I think is a better way to get started.

Stop #6: An Easier Approach

If you're new to the world of creating websites, I think you should take a look at Stackbit! (Of course I do, I work there and am writing on their blog.)

Stackbit is a site builder that specializes in Jamstack websites.

Instead of going through that entire process (the first five stops on the Jamstack journey), you could do it all yourself in much less time for much less money. After creating an account, Stackbit will give you a list of templates from which you can build your site. You'll then walk through the process of customizing it just for you.

The catch here is that Stackbit isn't just another WordPress or Squarespace, even though it may feel like it at first. Stackbit works to be super transparent about where your code and content live. What that means is that you can start this journey on your own, without a designer or a developer, at no cost other than your time. And you'll still have access to the code and content that powers your site. Once you're up and running, if you need a little help, that's when you can bring in a designer, developer, or SEO expert to make some suggestions or additions to your new site.

If that sounds like a walk in the park, give it a try!

In any case, I hope you've enjoyed your ride, and I'd love to learn more about your Jamstack Journey. Let's chat.

Separate Content from Website Code for Easier Editing

Sean C Davis — Tue, 24 Aug 2021 18:10:55 +0000

When it comes to turning a website design into a real thing (a website), a static site generator is an invaluable tool. It provides you with the ability to abstract reusable parts so you can write code more efficiently and more accurately.

We covered the process of moving from static HTML files to a static site generator (SSG) in the precursor to this article. Here we're going to look at taking your SSG game to the next level by transforming it into content-driven engine. Together, these two steps make up a few parts of The Jamstack Journey.

Let's dive in!

How a Content-Driven Website Works

There are two main steps in the process of transforming a templatized site into one that is content-driven:

Separate content from presentation
Abstract repeatable components

Separate Content from Presentation

The first step in the process is to separate content from presentation. Your templatized website likely has a number of HTML files representing the content of your site. (In our templatized example, we also used .njk files.)

For example, you might have a blog post represented as my-first-post.html that looks something like this:

It doesn't have any layout elements because those have all been abstracted away in your template, but it still has HTML code, which effects the structure — the presentation — of the page.

Converting this to a content driven approach means we can convert the HTML file into a content-based file, like markdown (e.g. my-first-post.md). And then that content can be fed into the main post layout. Like this:

If this doesn't make sense, don't worry yet. We're going to go through a real-world example.

Abstract Repeatable Components

This process forces us to develop a shape for our content. Doing so will help us uncover opportunities to further simplify templates by combining and abstracting repeatable structures. If this also has your head spinning, it's okay. We'll look at an example of this in action, too.

Benefits of a Content-Driven Website

The process of separating content from presentation has a number of benefits. These are the primary reasons I go through through this effort:

It reduces the potential for introducing new bugs through content. When you force your editors to write HTML code just to add content to your site, you are greatly increasing your risk for new bugs that come from unexpected or bad HTML code.
Less technical content editors can contribute without learning code.
It's more pleasant to author content. Markdown is built to get out of your way. Instead of wrapping a top-level heading in an <h1> tag, you just precede the line with #. There are no paragraph tags — they are inferred.
Markdown is faster to write, too! (At least once you get the hang of it.)

What about Content Management Systems?

If we're talking about separating content from presentation, shouldn't we be talking about content management systems (CMS), too?

(Great question, Sean.)

Yes, this would be the perfect time to introduce a CMS into your project. What we're doing here is substituting a more formal CMS with markdown files. Think of markdown files as the data coming from your CMS. In fact, you could technically pull content from a CMS and convert it to markdown files. I like this approach because a) it's simpler than wiring up a whole CMS, but b) can still work well with your setup if you choose to use a CMS.

Step 1: The Templatized Site

With that, let's get started!

Following the templatizing tutorial, we were left with this code. That's where we're going to begin for this exercise.

Add the contents of the example templatized project to some directory on your machine. Here's a link to download the larger example. After doing that, you can find the appropriate files in the 03-templated-site directory. Move these files into a new directory on your machine. Your folder's contents should look like this.

Now we're ready to get started. We're going to do a series of abstractions to get to our final content-driven site. What we'll focus on below are four steps that represent a smaller part of a larger effort. The code I'll share in the end will have made more abstractions, but we'll aim to arm you with the tools you need to get there.

To make sure everything is in order before we get going, it'd be safe to reinstall your dependencies and then start the development server.

npm install
npm run dev

Then visit localhost:8000 in your browser and you should see the site.

Step 2: Simplify Pages

The easiest step in this process is setting up our interior pages. Right now, our privacy and terms pages are .njk files, which means they are littered with HTML code. The beauty of Eleventy is that if we simply change the file extension in these files to .md they will work immediately.

Give it a try. Rename privacy.njk to privacy.md and terms.njk to terms.md. Notice that you don't even have to do anything and they work perfectly fine! That's the magic of markdown. Technically, HTML is valid markdown code.

But, even though it works, we have an opportunity to drastically simplify this content by removing the HTML. I ran the HTML code through an online converter. You could do the same or you could reference the new files (Terms here, and Privacy here).

⚠️ Notice that the little YAML markdown snippet at the top of these files did not change. That piece is still relevant so that Eleventy knows which template to use and how to pass on the title of each page to that template.

After these changes, your code should look like this and you should be able to visit localhost:8000/terms and localhost:8000/privacy with both looking as they did before you made the change.

Step 3: Shared Global Data

We could jump to the home page next, but that one is a doozy, so let's move on to something a little simpler first — shared global data. There is often content that you want to share across multiple pages or templates. Eleventy is built to support this with its global data files.

One example I see in looking at the site as it is right now are the details about the next event. So what I would do is place these details in their own data file in _data/next_event.json. Create that file and add the details:

{
  "date": "October 1, 2021",
  "time": "7 PM ET",
  "location": "Virtual",
  "cost": "Free"
}

We're using these in two places today — the home page jumbotron and the header in the content page. Since both files (index.njk and _includes/content-page.njk) are using the Nunjucks templating language, you can render this value using a Nunjucks variable.

For example, the code in the content page template would look like this:

<span class="hidden lg:inline-block lg:mr-2 xl:mr-3"
  >{{ next_event.date }}</span
>
<span class="hidden lg:inline-block lg:mx-2 xl:mx-3"
  >{{ next_event.time }}</span
>
<span class="hidden xl:inline-block lg:mx-2 xl:mx-3"
  >{{ next_event.location }}</span
>
<span class="hidden lg:inline-block lg:mx-2 xl:mx-3"
  >{{ next_event.cost }}</span
>

The home page can follow a similar pattern. Here is a summary of the changes I made.

It's a good idea to keep this pattern in mind and employ it whenever you find opportunities to share content (not code) among multiple pages or templates. For example, another use case might be to build a list of social media account URLs so that you can separate the links from the markup and style of the icons.

Give your browser another look to make sure that those values were updated as you'd expect.

Step 4: The Home Page

Let's take a look at the home page next. We won't abstract this in quite the same way as the interior pages. This is because when we templatized the site, we used a super generic template and put all the unique stuff directly in the home page.

What we want to do here is now extract the content from the home page so that it is trivial to edit without scrolling through the hundreds of lines of code. But we're in a good position to do that.

First, move your index.njk file to _includes/home.njk. Doing this effectively removes our home page. We still need that index page. But now we want it to be a content page. So let's create a new file in the root of the project and call in index.md.

Refresh your browser and see that there's nothing there! That's because Eleventy is now reading this as your home page, but there's no content and you haven't specified a layout. So let's do that. Change the file to look like this:

---
layout: home
---

Now refresh your browser and we're back.

Then we can move through the file meticulously and extract elements one at a time until we have separated all our content from the template.

For example, say we wanted to adjust the copy under "Unmute yours" in the jumbotron.

Maybe we make a new object for jumbotron and then add a body section to it. Your index.md file would look like this:

---
layout: home
jumbotron:
  body: |-
    Join us for an evening of storytelling with some of your favorite fellow
    nerds. We'll laugh. We'll cry. We may even hear a story without any
    industry jargon!
---

And you could replace the section in _includes/home.njk to look like this:

<p class="max-w-md mb-8 mx-auto md:mx-0">
  {{ jumbotron.body }}
</p>

This is a long and often tedious process, but it's a game-changer when it comes to editing your site down the road. I'll leave the rest up to you and share where I ended up after going through the exercise. But first I want to talk about the process of abstracting components.

Step 5: Abstracting Components

Extracting content from your pages and templates requires that you define the structure of your data. In Step 4, we could see the beginning of that structure — e.g. jumbotron was going to be its own section, presumably with multiple properties within it.

The resulting structure can help you determine where you can tighten up your template code further by looking for repeatable patterns.

For example, in this home page, each of the speakers has a similar shape to its content. So, even though you could define each speaker individually, it probably makes sense to develop a repeatable pattern, like this:

speakers:
  - name: Speaker Name
    position: Title / Company
    fun_fact: Fun Fact
    image: /images/speakers/speaker-01.png
    social:
      twitter: "#"
      facebook: "#"
      instagram: "#"
  - name: Speaker Name
    position: Title / Company
    fun_fact: Fun Fact
    image: /images/speakers/speaker-02.png
    social:
      twitter: "#"
      facebook: "#"
  - name: Speaker Name
    position: Title / Company
    fun_fact: Fun Fact
    image: /images/speakers/speaker-03.png
    social:
      twitter: "#"
  - name: Speaker Name
    position: Title / Company
    fun_fact: Fun Fact
    image: /images/speakers/speaker-04.png
    social:
      twitter: "#"
      facebook: "#"
      instagram: "#"

This repeatable pattern hints that we could also abstract the code. Instead of having individual HTML for each speaker, we could create another include template and render the content of each speaker.

Our _includes/home.njk file would include this:

<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-{{ lineup.speakers.length }}">
  {% for speaker in speakers %}
    {% include "speaker.njk" %}
  {% endfor %}
</div>

And then _includes/speaker.njk could look like this:

<div class="mx-4 mb-8 lg:mb-0 template-home--speaker">
  <span class="block mb-2">
    <img src="{{ speaker.image }}" alt=""/>
  </span>
  <strong class="block mb-2 text-lg">{{ speaker.name }}</strong>
  <span class="block text-sm">
    <em>{{ speaker.position }}</em>
  </span>
  <span class="block text-sm">{{ speaker.fun_fact }}</span>

  <div class="flex items-center justify-center mt-4">
    {% if speaker.social.twitter %}
      <a href="{{ speaker.social.twitter }}" class="mx-1 hover:opacity-75 transition-all duration-300">
        <span class="inline-block bg-red text-white rounded-full p-2 overflow-hidden h-8 w-8 component--icon">
          {% include "svg/twitter.svg" %}
        </span>
      </a>
    {% endif %}
    {% if speaker.social.facebook %}
      <a href="{{ speaker.social.facebook }}" class="mx-1 hover:opacity-75 transition-all duration-300">
        <span class="inline-block bg-red text-white rounded-full p-2 overflow-hidden h-8 w-8 component--icon">
          {% include "svg/facebook.svg" %}
        </span>
      </a>
    {% endif %}
    {% if speaker.social.instagram %}
      <a href="{{ speaker.social.instagram }}" class="mx-1 hover:opacity-75 transition-all duration-300">
        <span class="inline-block bg-red text-white rounded-full p-2 overflow-hidden h-8 w-8 component--icon">
          {% include "svg/instagram.svg" %}
        </span>
      </a>
    {% endif %}
  </div>
</div>

That's 30-some lines of HTML, instead of more than 100! And if you want to change the presentation of a speaker, you only have to change it in one place.

Here are the changes I made to the home page. And here is what the resulting code looks like. At this point, you have a website that is not just easy to edit its structure or presentation, but it's also trivial to create new pages or adjust values on the home page without searching through a bunch of HTML code to get there.

Go ahead, try it! Create a new .md file. Give it a content-page layout (like Terms and Privacy) and title, then see it come to life!

Now that you now how to templatize a static HTML site and you can separate its content from presentation, you have two very important tools necessary to create rock solid websites with the Jamstack.

How to Convert Static HTML into Powerful Templates

Sean C Davis — Tue, 10 Aug 2021 17:54:52 +0000

You've gone through the design process in building a website, but now you're left with a handful of HTML files, along with some images and one or more CSS and JavaScript files, and you want to know what to do with them? Great! Let's talk about it.

You could deploy (i.e. publish) them, and eventually you will, otherwise no one will see your site. But deploying at this point is only going to get you so far. Inevitably, you’re going to want to change something with the site, and then what? Are you going to go all the way through the design process again? That sounds … painful.

A more sustainable approach is to take the static HTML content you were given and templatize it! Make it easier for you to work with — to make changes and to create new pages — when the need arises.

Why templatize a website?

This process has one major benefit — reusability. It makes the act of adjusting structure or content relatively trivial when compared with having to work with individual HTML files. That process can be further enhanced by separating content from presentation, so that when all you need to do is change a few words, you know right where to go and never have to mess with any of the code. (We have a detailed guide for that, but you’ll want to follow this one first.)

Consider two typical and simple content pages that most sites have — Terms & Conditions and Privacy Policy. They often have the same header and footer. It’s just the content in the middle of the page that differs (though the structure is likely similar). With those pages as separate HTML files, when you want to change something in a shared section — like the header or footer — you have to make the change in both places.

Expand that example to a site that has hundreds of pages with a similar structure (like blog posts). You’d be making that change hundreds or thousands of times, depending on the size of your site.

Following a software development principle called don’t repeat yourself (often referred to as DRY code), you could build the site with reusable pieces. Then you can make each change once and have it work everywhere. This is the magic of templatizing.

How templatizing works

When you have no templates and only HTML, the code on each page is unique and lives within its own file. Take a super simple site that has a home page (index.html), along with Terms (terms.html) and Privacy (privacy.html) pages. Your files look like this, where the dark blue boxes represent the code unique to each page:

Now let’s say the header on the home page is unique, but the header on the Terms and Privacy (i.e. interior) pages could be shared. And maybe the footer is the same on every page. Then we could make the header and footer into their own files and share them among multiple pages. Like this:

After creating these templates, changes to the footer only need to be made once and every page is updated to reflect the new changes.

This is a super simplistic view to show the power that even small abstractions can add to the longevity of your site. What we’ll do here will be slightly different in practice.

But how do we actually do this?

Static site generators are here to save the day!

Unfortunately, the web isn’t built to work with templates. We can’t actually just add a footer.html file and then tell every page to include it and have the browser work. In the end, the browser expects a single HTML file. In other words, the browser actually wants the non-templatized version of the two scenarios above.

But that’s not how we want to work. It’s tedious and prone to errors. If you want the footer to look the same everywhere, it should be the same everywhere. Otherwise, you risk making inadvertent changes on random pages. To help with this process we can use a tool called a static site generator.

There are many to choose from, perhaps including some popular ones you may have heard of, such as Jekyll, Gatsby, Next.js, or Hugo. Here we’re going to use one called Eleventy.

What’s so great about Eleventy?

Eleventy isn’t as popular as some of its competition, but it is supreme in its approach, which is simplicity. It is modeled after Jekyll, which provides a super low barrier to getting started when compared with the rest of the field. But unlike Jekyll, it is written entirely in JavaScript, which makes it a great fit for folks getting started with building websites.

Eleventy can also be super powerful. It takes more customization as your site grows in complexity, but it can grow with you. My site has several hundred pages and, at the time of writing this, is built entirely through Eleventy.

Okay, now are you convinced you should templatize those HTML files?

Hooray! Me too.

Let’s do it!

Step 1: The Static Site

Let’s work through this process together using a real-world example. We’re going to build a super simple version of the Unmute website. (Unmute is a real thing — a side project I’m working on with a few nerdy friends.)

We’ll have a unique home page along with two similar content pages, mimicking a Terms & Conditions page and a Privacy Policy page.

Let’s say the output of the whatever process you went through to obtain the files for your site left you with this mess:

css/styles.css to hold all your styling for the site.
js/bundle.js which handles the carousel at the bottom of the home page.
images as a house for all visual assets.
index.html to represent your home page.
content-page.html to represent all other internal pages.

Gotcha!
Take note that we’re making a big assumption here. We’re assuming that you won’t need to mess with your styles.css or bundle.js file. They were bundled up nicely for you by the freelance dev and you won’t need to make changes.

In the real world, it can be a tricky process to take big, bulky, obfuscated CSS and JS files and create a method for adding to them. And it gets even more complicated if you ever have to go back to the developer for changes after you’ve customized one of these.

As a result, we’re considering that process outside the scope of this guide. However, if this need arises, I’ve written a couple relatively simple guides on how to achieve this for both CSS and JavaScript.

Step 2: Create a New Project

Add the contents of the example static project to some directory on your machine. Here’s a link to download the larger example. After doing that, you can find the appropriate files in the 02-static-site/www directory. Move these files into a new directory on your machine. Your folder’s contents should look like this.

Step 3: Setup Eleventy

We’re going to assume you have a computer that is setup for web development. (If not, here’s a guide I wrote on setting up a new Mac for development.)

Once you’re ready to go, open up your command line or terminal application, change into the project directory and install Eleventy:

# navigate to your new project
cd path/to/my/project

# setup project for Eleventy
npm init -y

# install eleventy
npm install -D @11ty/eleventy

Note: If you’re tracking your changes with Git, this is a great spot to initialize the repository (git init) and add node_modules to a .gitignore file. If you’re not working with Git, don’t worry about this right now.

I like to add a few shortcuts after this installation to make working with sites more consistent across my machine. Open your package.json file and add the following to the scripts section:

{
    // ...
    "scripts": {
        "build": "eleventy",
        "clean": "rm -rf _site",
        "dev": "eleventy --serve --port 8000"
    }
}

Here’s what that file should look like at this point.

Now we have a way to run an Eleventy development server. Run the following command:

# start eleventy server
npm run dev

You should now have a dev server running at localhost:8000. And you’ll notice you now have a new _site directory in your project. Eleventy did this automatically for you.

You can open your browser and visit localhost:8000 to see your site, and … something doesn’t look right.

That’s because we didn’t tell Eleventy where our assets are. To do this, we must add an Eleventy config file at .eleventy.js:

module.exports = function (eleventyConfig) {
  // Copy static assets over to _site directory.
  eleventyConfig.addPassthroughCopy("css");
  eleventyConfig.addPassthroughCopy("images");
  eleventyConfig.addPassthroughCopy("js");
  // Return configuration object.
  return {}
};

Give the browser a refresh and everything should look good again!

Note: Throughout this guide, when making changes, you may have to clear the cache on your browser. Most browsers have an option to reload while clearing the cache for that site.

Step 4: The Default Layout

In Eleventy (and most static site generators), each page is wrapped in a layout. A layout is just a fancy term for a template. We’re going to begin by creating a default layout. This will be code that every page uses. We do this because, as we’ll soon see, Eleventy supports nesting layouts within one another. So what we’re going to do here is define our base layout.

In looking at index.html and content-page.html, the code that is consistent between the two is mostly contained within the <head> tag, but also includes a few lines at the very bottom of the file. Here’s what it looks like:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <link rel="apple-touch-icon" sizes="180x180" href="/images/favicon/apple-touch-icon.png"/>
    <link rel="icon" type="image/png" sizes="32x32" href="/images/favicon/favicon-32x32.png"/>
    <link rel="icon" type="image/png" sizes="16x16" href="/images/favicon/favicon-16x16.png"/>
    <link rel="manifest" href="/images/favicon/site.webmanifest"/>
    <link rel="mask-icon" href="/images/favicon/safari-pinned-tab.svg" color="#5bbad5"/>
    <meta name="msapplication-TileColor" content="#da532c"/>
    <meta name="theme-color" content="#ffffff"/>
    <title>Stackbit Demo: Unmute</title>
    <link rel="stylesheet" href="/css/styles.css"/>
    <script>
      function onInit(callback) {
        if (typeof App !== "undefined")
          return callback();
        setTimeout(onInit, 250, callback);
      }
    </script>
  </head>
  <body class="font-default">

    <!-- This was the unique code -->

    <script src="/js/bundle.js"></script>
  </body>
</html>

Put that code in a new file: _includes/default.njk. And in the spot where the unique code existed, add the Nunjucks variable content. (More on this in a moment.) Your resulting file should look like this.

Three items are important to note in this new template:

We changed the file extension from .html to .njk. This means we’re using Nunjucks as our templating language. Eleventy supports a number of languages. Nunjucks is nice for staying with our theme of using JavaScript. And it’s also fairly minimalistic, which is nice for our example.
We added a single Nunjucks variable, content and passed a safe filter to it. content tells Nunjucks to render the content of the each page in that area. That means all of our page content will fall where you see {{ content | safe }}.
The _includes directory has some special characteristics that make it easy to … well, include files. Read more here.

Nothing has changed if we refresh the browser because we haven’t wired these up yet. When we go to the home page, we’re still just looking at index.html, which isn’t using our new layout yet.

Step 5: Wrap the home page in the new layout

Let’s adjust our home page to use the new layout.

Begin by changing index.html to index.njk. This is going to help us in the future when we want to use Nunjucks variables or tags in the page.

Now, remove all the code you extracted to create the layout and refresh your browser.

What the heck? You’re back to a page without styles. What happened?

What happened is that you removed your references to the CSS and JS files, which were in the <head> and near the bottom of the <body>, but you didn’t tell Eleventy to use a layout. So let’s change that. Add the following at the top of your index.njk file:

---
layout: default
---

Now refresh the browser and you should see your styles come back!

This style code — three hyphens, then some code, then three more hyphens — is called frontmatter. It’s like code before the code. It provides us a space to place meta information about that file that won’t ultimately be written to your browser screen.

The last thing to note here is that you will want to either remove or change the comments in your code. Nunjucks comments look a little different than HTML comments (although they will ultimately still be treated as comments, so you can ignore this if you’d like).

Any code between  is an HTML comment. Either remove these or change them to {# and #}.

In the end, this is what your new index.njk file should look like.

Step 6: Content Pages

Now let’s add a couple plain content pages. Our developer delivered a generic content page to us called content-page.html. We want to use that to create multiple pages. In this case, maybe those are Terms & Conditions and Privacy Policy pages.

To do this we first want to make our generic content page a layout. To do that rename content-page.html to content-page.njk and move it into the _includes directory.

Now, here’s a really weird and super cool thing about Eleventy — we can nest layouts in other layouts. What that means is that because the content page has code that we’ve already used in _includes/default.njk, we can reuse that with the content page layout.

To do this, remove the shared code from _includes/content-page.njk and specify the layout in the frontmatter at the top of the file.

Now you can create two new files, terms.njk (or terms.html — we aren’t doing anything special at this point) and privacy.njk. Add some content (I used a generator for the content and you can use what I have) and tell Eleventy to use the “content-page” layout:

layout: "content-page"

Now you can go to localhost:8000/terms and localhost:8000/privacy and you should see your nicely-formatted content.

Here are the links to these files at this stage:

Step 7: Extracting Shared Code

Now you’re in good shape and have a pattern to create new pages with a nice layout. Any new file you create with the “content-page” layout will now have a header and footer wrapping your content.

But, we still have an opportunity for some improvement. While we are using a layout to create multiple pages, which means we’re sharing code, we do still have some duplicated code. Now the home page (index.njk) and the content page layout (_includes/content-page.njk) have separate footers. Even though they look the same, you’d have to edit the content in both if you wanted to make a global change.

Let’s make that easier. Pull the footer content into its own file in the _includes directory, _includes/footer.njk (see here). Then remove that shared code from the home page and content page layout and replace it with the include Nunjucks tag:

{% include "footer.njk" %}

(See the new index.njk and _includes/content-page.njk files.)

Now you can make the change once and see it work everywhere. For example, you could add links to the terms and privacy pages.

Note: You could have chosen to include the footer directly in the default layout, or even reference in in the default layout. This is entirely up to you and your project. In this case, I’m accounting for some future template that won’t want the footer. But if we’re sure every page wants the footer, maybe it makes sense to put it in the default layout.

Other Opportunities

As your site grows, you’ll find other opportunities for improvement and abstraction (abstraction being the process of cleaning up code to be shared).

Shared Images

For example, many of the shapes you see on the pages are SVG elements. They are images, but represented with HTML code. And many of them are used more than once.

You could remove the <svg> elements and turn them into their own file in the _includes directory. (You could even put them in their own subdirectory so they are grouped together.) Then you can reference them with a Nunjucks tag.

Unique Titles

You may also run into the opposite issue at some point, where you’ll have code or content in a shared space, but you want it to be unique to some particular template. For example, you’ll want the title of the page (contained in the <title> attribute) to be unique to each page. But that code is nestled up in the default layout.

This is where Nunjucks variables and page frontmatter comes into play. Take the terms page, for example. You could add a title attribute in its frontmatter:

layout: "content-page"
title: "Terms & Conditions"

Then, in the _includes/default.njk layout, you can use the title variable.

<title>{{ title }}</title>

You could make the same change to the _includes/content-page.njk body so that you don’t have to write the <h1> on every page. Something like this:

<h1>{{ title }}</h1>

The world is your oyster when it comes to finding these efficiencies. It’s all about how you want to work and how you want the framework (Eleventy) to work for you.

I bucketed a handful of these changes together and did them all at once. Here are the changes I made and the files in the project at this point.

Wrapping Up

Phew! Take a break, give yourself a pat on the back. This process can be a harrowing one, especially the first time around. If you’ve made it through, you deserve a break and some ice cream.

To quickly recap. What we started with was a jumbled mess of HTML files, handed to you by some developer. We took those files and turned them into layouts (or templates) that we could use to quickly create new pages with the same design.

Where do we go from here?

I’m glad you let me ask that question on your behalf, because we have a great next step! Instead of using .html or .njk files for our content, you can double-down on frontmatter and markdown to create a truly powerful editing experience that gets all the code out of your way and keeps you focused on only the content.

And, lucky for you, we have a guide to keep this thing going and to walk you through that process.

But first, go get that ice cream.