Most websites contain the same or very similar layouts on multiple pages, e.g. header and footer. There also might be a few different hero section designs and a few different CTA section designs. Imagine having 10 product pages each containing three 2-column sections with a text description in the left column and a screenshot in the right column. Each of these product pages may also have a CTA section design but with slightly different text and links. It’s common to put shared CSS in a shared CSS file, e.g. shared.css, common.css, or global.css. This especially makes sense for the header and footer, which are usually shown on all pages. But over time, that shared CSS file can become very long because you may have a lot of CSS for many different common sections. This can make it difficult and dangerous to edit code for just one particular section. It can also make it very difficult if you want to copy a section on one page to add to another page. If the HTML, CSS, and JS for the section aren’t isolated, you may not copy all the necessary code, not to mention you could end up with inconsistencies between two or more sections that should have the same design.
Consolidating all CSS into the fewest files possible is good for website performance (the fewer files, the fewer network requests), but nowadays, it’s common for websites, including simple static websites, to go through an automated build process to optimize the files before publishing them. The build process can do many things like minify and combine multiple CSS and JS files into single CSS and JS files, add prefixes to CSS using tools like PostCSS auto-prefixer, etc.
Following is one simple approach to grouping HTML, CSS and JS by website section. This approach can also be used for any part of a website like blocks within a section, but to keep things simple, we’ll just look at sections which I define as horizontal rows of related content, e.g.
- header section
- hero section design 1
- hero section design 2
- features section design 1
- features section design 2
- resources section
- CTA section
- footer section
Here’s one possible file structure.
my-website/
├─ src/
│ ├─ index.njk
│ ├─ index.css
│ ├─ index.js
│ ├─ product1/
│ │ ├─ index.njk
│ │ ├─ index.css
│ │ ├─ index.js
│ ├─ product2/
│ │ ├─ index.njk
│ │ ├─ index.css
│ │ ├─ index.js
│ ├─ components/
│ │ ├─ header/
│ │ │ ├─ header.njk
│ │ │ ├─ header.css
│ │ │ ├─ header.js
│ │ ├─ footer/
│ │ │ ├─ footer.njk
│ │ │ ├─ footer.css
│ │ │ ├─ footer.js
│ │ ├─ section1/ (e.g. hero layout design 1)
│ │ │ ├─ section1.njk
│ │ │ ├─ section1.css
│ │ │ ├─ section1.js
│ │ ├─ section2/ (e.g. hero layout design 2)
│ │ │ ├─ section2.njk
│ │ │ ├─ section2.css
│ │ │ ├─ section2.js
│ │ ├─ section3/ (e.g. features layout design 1)
│ │ │ ├─ section3.njk
│ │ │ ├─ section3.css
│ │ │ ├─ section3.js
│ │ ├─ section4/ (e.g. testimonials layout design 1)
│ │ │ ├─ section4.njk
│ │ │ ├─ section4.css
│ │ │ ├─ section4.js
├─ build/
│ ├─ index.html
│ ├─ index.css
│ ├─ index.js
│ ├─ product1/
│ │ ├─ index.html
│ │ ├─ index.css
│ │ ├─ index.js
│ ├─ product2/
│ │ ├─ index.html
│ │ ├─ index.css
│ │ ├─ index.jsIn the src (source) folder, I’m using Nunjucks (njk) files instead of HTML files so they can include logic and pull in the components (partials). When the source files are processed, the built HTML files show up in the “build” folder. For the home page source file (index.njk), the structure of the code could be like this
<html>
<head>
{% include "/src/components/header/header.css" %}
{% include "/src/components/footer/footer.css" %}
{% include "/src/index.css" %}
</head>
<body>
{% include "/src/components/header/header.njk" %}
... some HTML ...
{% include "/src/components/footer/footer.njk" %}
{% include "/src/components/header/header.js" %}
{% include "/src/components/footer/footer.js" %}
{% include "/src/index.js" %}
</body>
</html>Note that the home page has its own CSS and JS files for elements that are not part of a component. When this file is built, the CSS and JS files will be combined (Netlify can do this automatically) and the included header and footer njk references will be replaced with their contents, e.g.
<html>
<head>
<link rel="stylesheet" href="index-435kl3jl3j.css">
</head>
<body>
<header>
<p>FOO Website</p>
<ul>
<li>Home</li>
<li>Product 1</li>
<li>Product 2</li>
</ul>
</header>
... some HTML ...
<footer>
Copyright 2023
</footer>
<script src="index-43533lj344.js"></script>
</body>
</html>Here’s another example. For product page 1 (product1/index.njk), the file contents may look like this
<html>
<head>
{% include "/src/components/header/header.css" %}
{% include "/src/components/section1/section1.css" %}
{% include "/src/components/section4/section4.css" %}
{% include "/src/components/footer/footer.css" %}
{% include "/src/product1/index.css" %}
</head>
<body>
{% include "/src/components/header/header.njk" %}
{% set title = "Product 1" %}
{% set heroImage = "product1.jpg" %}
{% include "/src/components/section1/section1.njk" %}
... some HTML ...
{% set text = "Try Product 1 Now" %}
{% set link = "/product1/free-trial/" %}
{% include "/src/components/section4/section4.njk" %}
{% include "/src/components/footer/footer.njk" %}
{% include "/src/components/header/header.js" %}
{% include "/src/components/section1/section1.js" %}
{% include "/src/components/section4/section4.js" %}
{% include "/src/components/footer/footer.js" %}
{% include "/src/product1/index.js" %}
</body>
</html>In the code example above, we’re passing some variables into components section1 and section 4. That allows us to reuse a component’s layout and design while changing its content. Since product pages usually look very similar, the code for product2/index.njk might look like this
<html>
<head>
{% include "/src/components/header/header.css" %}
{% include "/src/components/section1/section1.css" %}
{% include "/src/components/section4/section4.css" %}
{% include "/src/components/header/footer.css" %}
{% include "/src/product2/index.css" %}
</head>
<body>
{% include "/src/components/header/header.njk" %}
{% set title = "Product 2" %}
{% set heroImage = "product2.jpg" %}
{% include "/src/components/section1/section1.njk" %}
... some HTML ...
{% set text = "Try Product 2 Now" %}
{% set link = "/product2/free-trial/" %}
{% include "/src/components/section4/section4.njk" %}
{% include "/src/components/footer/footer.njk" %}
{% include "/src/components/header/header.js" %}
{% include "/src/components/section1/section1.js" %}
{% include "/src/components/section4/section4.js" %}
{% include "/src/components/footer/footer.js" %}
{% include "/src/product2/index.js" %}
</body>
</html>I reused the components but changed the value of the variables that are referenced in the components.
To prevent code conflicts, you can specify an ID in the first element of each component. For example,
section1.njk
<div id="section1">
... some HTML ...
{{text}}
{{link}}
</div>section2.njk
<div id="section2">
... some HTML ...
{{text}}
{{link}}
</div>Then, in the component’s CSS, to prevent CSS conflicts, you can prefix all rules like this
section1.css
#section1 .intro {
... some CSS ...
}
#section1 .features {
... some CSS ...
}section2.css
#section2 .intro {
... some CSS ...
}
#section2 .features {
... some CSS ...
}Similarly, with the JavaScript component file, you can do something similar, e.g.
section1.js
$("#section1 .intro")...section2.js
$("#section2 .intro")...Another benefit of this approach is you can create a page showing a preview of all components you have. When you want to create a new page, you can browse the list of component previews to see if you can reuse an existing component or decide if you need to create a new component.
Separate content from design
In the examples above, we’re specifying content in variables above each “include”. This can result in a very long template. A better approach is to move the content to a separate data file in JSON format. Let’s update our file structure as follows:
my-website/
├─ src/
│ ├─ index.njk
│ ├─ index.css
│ ├─ index.json
│ ├─ index.data.json
│ ├─ product1/
│ │ ├─ index.njk
│ │ ├─ index.css
│ │ ├─ index.js
│ │ ├─ index.data.json
│ ├─ product2/
│ │ ├─ index.njk
│ │ ├─ index.css
│ │ ├─ index.js
│ │ ├─ index.data.json
...Now, let’s move the data from the njk files to the JSON data files. For product page 1 (product1/index.njk), the data file may look like this:
{
"hero": {
"heading": "lorem ipsum",
"copy": "lorem ipsum",
"ctaLabel": "Try Now",
"ctaLink": "/forms/vmdr/",
"bgImage": "apps/hero-bg-apps.png"
},
"features": [
{
"text": "lorem ipsum",
"link": "/forms/vmdr/",
},
{
"text": "lorem ipsum",
"link": "/forms/pm/",
},
{
"text": "lorem ipsum",
"link": "/forms/cmdb/",
},
]
},
"testimonials": {
"slider": true,
"quotes": [
{
"content": "lorem ipsum",
"logo": "logo/logo.svg",
"logoWidth": "140",
"name": "lorem ipsum",
"jobTitle": "lorem ipsum"
},
{
"content": "lorem ipsum",
"logo": "logo/logo.svg",
"logoWidth": "140",
"name": "lorem ipsum",
"jobTitle": "lorem ipsum"
},
{
"content": "lorem ipsum",
"logo": "logo/logo.svg",
"logoWidth": "140",
"name": "lorem ipsum",
"jobTitle": "lorem ipsum"
},
]
}
}The JSON data file contains 3 blocks,
- one for the “hero” section / component (section1.njk),
- one for the “features” section / component (section3.njk),
- one for the “testimonials” section / component (section4.njk)
To get the component files (section1.njk, section2.njk) to read the data from the data files (product1/index.data.json, product2/index.data.json), we’ll need to update the syntax a bit.
For product page 1 (product1/index.njk), the file contents may look like this
<html>
<head>
{% include "/src/components/header/header.css" %}
{% include "/src/components/section1/section1.css" %}
{% include "/src/components/section4/section4.css" %}
{% include "/src/components/footer/footer.css" %}
{% include "/src/product1/index.css" %}
</head>
<body>
{% include "/src/components/header/header.njk" %}
{{> /src/components/hero page.hero }}
... some HTML ...
{{> /src/components/section3 page.features }}
... some HTML ...
{{> /src/components/section4 page.testimonails }}
{% include "/src/components/footer/footer.njk" %}
{% include "/src/components/header/header.js" %}
{% include "/src/components/section1/section1.js" %}
{% include "/src/components/section4/section4.js" %}
{% include "/src/components/footer/footer.js" %}
{% include "/src/product1/index.js" %}
</body>
</html>Note that were passing page.hero, page.features, and page.testimonials, which only contains the JSON data for those sections, to their respective components (hero.njk, section3.njk, section4.njk).
The corresponding component files may look like this
section1.njk (hero component)
<section>
...
<div style="background: url({{{bgImage}}});">
<h1>{{{heading}}}</h1>
<p>{{{copy}}}</p>
<a href="{{{ctaLink}}}">{{{ctaLabel}}}</a>
</div>
...
</section>section3.njk (features component)
<section>
...
<h1>Features</h1>
{{#each quotes}}
<a href="{{{link}}}">{{{text}}}</a> <br>
{{/each}}
...
</section>section4.njk (testimonials component)
<section>
...
<h1>Testimonials</h1>
<div class="{{#if slider}}swiper{{/if}}">
{{#each quotes}}
<div>
<img src="{{{logo}}}"> width="{{{logoWidth}}}">
<blockquote>{{{content}}}</blockquote>
{{{name}}}, {{{jobTitle}}}
</div>
{{/each}}
</div>
...
</section>You can even have nested components. For example, here is a button component.
button.njk
<a href="{{link}}" class="myButton">{{text}}</a>You can insert the button component in the hero component as follows:
section1.njk (hero component)
<section>
...
<div style="background: url({{{bgImage}}});">
<h1>{{{heading}}}</h1>
<p>{{{copy}}}</p>
<a href="{{{ctaLink}}}">{{{ctaLabel}}}</a>
{{>
/src/components/button
text="Sign Up"
link="/sign-up/"
}}
</div>
...
</section>TO DO: create POC in GitHub
