Introduction
In the initial stages of my web development career, platforms like WordPress was all you need to setup marketing websites, but as web development standards like Pagespeed, SEO & performance become more directly connected to important metrics like conversion, page ranking and user experience, brands now demand are more native or light weight experience foroing the benefits of having a user-friendly drag and drop WordPress interface.
It seemed like before business, developers where the only ones who used statc sites for their blogs, documentation & project sites. Building websites was basically split between developer-friendly vs user-friendly approaches. While a lot of user friendly platforms like Webflow are catching up to provding very performant websites, some big brands prefer to spin up their own codebase for adminstering their sites statically.
Beyond the useful advancements from HTML to adopting various templating languages like pug, handlebars & workflow tooling like gulp, webpack, vite, there are other considerations or learnings from my experience build landing pages.
Learnings
1. Seperate Concerns
While we have the MVC - Model, View, Controller paradigm in web applications, I like to think of websites in terms of content, layout & media. Where content can be best described by looking at the structure of a basic markdown file which has an section for storing json like data as well as the rest for storing text content. Content basically influences how layouts would turn out and can include media assets in them.
So how seperation of concerns would usually turn out involves
- Detaching content from the layout and making them only editable via markdow file or CMS integrations.
- Layouts should be handled with reusablity & modularity in mind will taking into account how edge cases in content would affect it's outlook
- Media must be handled seperately as it goes beyond just including a link to a file to involve managing page load performance, pagespeed scores, best practises, affecting build times etc.
2. Make Site Configuration Accessible
It might seem obvious that the content team need access to those markdown files to publish content, but often times someone from another team or management might want to update the navigation themseleves, or the footer links or form id or even a javascript interaction. To save yourself some headaches or regular edits it's best you think of everything on the site as being configurable through content edit via markdown or CMS integration.
3. Access Management & Change Approval
What every tools you are using in your pipeline from updation of content to release, there needs to be a process for ensuring only approved content goes live, Github provides some good change approval checks and some CMS also incoporates this. You can use Git blame or activity logs of your CMS to know who changed what and when.
4. Deployment speed matters
Everyone might be fine with a 15min build time, until someday everyone wants to put some piece of content up in 3mins or take another down like yesterday. If the framework you are using has a massive build time, then consider switching, modern frameworks like Astrojs keep improving regularly. Some ways to ensure a faster build time include
- Add conditional build steps in your workflow manager, if you are using Github actions or Circle CI, you can include steps that can be skipped if need be
- Run some operations post-build e.g non-critical checks or checks that take too long can be setup to run immediatly after build and deployment is complete
- Avoid uncessary function calls in your static site setup, for example sending data to algolia all the time,
- Use caching, if you pull a lot of data from a CMS and it takes too long to download, you can as well store it locally or cache parts of it to save time
- Avoid having media files in the same project files, because they consume time uploading each time you deploy your project you can use services like Cloudinary or imgix to manage your files
- You can also setup some kind of selective deployment, that builds only content that is changed (should write about this in future)
5. Setup Thorough Observability
Do not assume to trust your code or setup, something can go wrong due to your own faults, negligence or sometimes totally unexpected from something attached to your process. Take note the more the pages and process you have the more the items to observe increase so I encourage you to adopt automation in your workflow early on. Some observability measures include.
- Collect JS errors using tools like sentry before they get reported by a user or team
- Track visual or text changes using tools like visual ping
- Tracking your critical or business flows using tools like New relic or cypress
- Add content/ data validation using tools like zod, joi and yup
- Setup compilance trackers that check regularly so you know when something is missing
- Monitor 3rd party services & apis you some, sometimes some of them change api structure which can end up breaking your layouts
- Monitor site uptime, domain name renewals or SSL using tools like uptime robot
6. Make content reusable everywhere
Looking into the information architecture of things, blog posts need to have a page as well as show up in the blog listing page. Futher more, we cloud want to include them on a banner in the footer or on a CTA somewhere. It would be silly and prone to errors if one has to edit the same content from multiple areas all the time, hence it is wise to consider the reusability of both list, object or text content in the site.
7. Think of extensibility from the start
I have noticed that sometimes, teams get stuck thinking about the best approach towards deploying a project or a new feature. Most times the excuse is that they want something great from start. My general rule is to setup a solid foundation when you can or scaffold something simple if it's taking too long and return to it later. Sometimes the client might encourage you even to take a simpler approach as it's no big deal, but be rest assured that it would some become a big deal so if possible setup your tasks or project in such a way that they are easily extensible later or would require least effort refactoring if need be. This is crutual especially where a lot of content depends on the structure of things from the start. For example, the author information for a blog post content is better setup as an array of authors in the frontmatter than just a single author. One can just use only the first author in the list if the site only just reuires one author per post. It would be easier to extend once a post can have mutiple authors. Further more instead of just providing an author id, you can provide a way to customize on-page/post information about the author. Some points on extensibility to think on include
- Compliance measures
- Multi-linugual support
- Service integrations
- Splitting, or migration
8. Leverage Automation
Automation is not negotiable as content & processes scales. You can get warn down if you keep out repitive tasks without considering alternatives. From time to time, take a break and ask yourself if this thing you do everyday can be automated away. One strong reason to leverage automation is to save you time so you can focus on more creative things that have impact. Automation is even more necessary in monitoring and securing the integrity of your site. Some examples of things to automate
- OG image
- Post thumbnail
- js yaml to update frontmatter of many markdown files
- Sitemap & RSS feed
- Content validations
- PageSpeed checks
- Broken links, images or 404 page checking
- Typo & lanugauge checking - basically tag the elements that needs typo checking on your page and use a service or script to check and report
- Image processing
- Data pipeline for reporting
9. Leverage data points
The frontmatter or data from CMS api usually have a field, value format which could be in a list or object format. These fields could be of various types like text, date, number which can be used to infer scale, order, identity etc. Sometimes they work in combination and sometimes their precense or absence can depit something is wrong
- Data fields can be used to setup reporting for stale content, filter out future content
- Do not provide an information twice e.g If slug can be the file name, then no need to provide it in the file again except perharps as an over-rides
- Use them in automations e.g Use post title in OG image generation
- Setup validations on them. For example character counts, list size etc.
10. Support the Teams with Libraries & Dashboards
Some additional setups are required sometimes to facilitate working with other times. For example site administrators might need a place to upload images, videos and pdfs. Sometimes to assure the designers on the project you are on the same page, you would need to share links that show records of all the styles or site sections adopted. When you have setup custom scripts for automation and reporting, you might need a user friendly dashboard to enable team members also trigger automations or export reports.
- Layout libraries
- Style guide
- Media libraries
- Reporting & Feature Dashboards
11. Don't Skip Dev Experience
If you are previlegdge to have other developers working with you on the team, it's best to constantly evaluate if things can be done better and suggest them or take them up. Sometimes might seem hard intially but they would save a lot of headaches in the future. Dont be afraid to setup your own tool or extend exisiting ones.
- Use typescript
- Setup validators
- Use prettier & ESlint
- Setup proper documentation
- Use Husky for pre-commit checks
- Leverage peer programming
- Use & extend packages, libraries and frameworks
12. Understand & Organize How Data Flows
Back to making a site more configurable, I usually take this approach of organizing by site -> layout -> page group -> page -> sections/ panels. Meaning any content from markdown or apis would come from a site level, trickle down fro the layout, page group down to the individual panels in a page. There are other ways of arranging this for example where there is no page grouping. I adopt page group so that I can apply similar configuration to pages found in that particular group.
13. Use overrides & defaults with concion
After understanding the flow of content through the site, you must also have an understanding of which destinations require a default value if non is provided and also how content from the various flow points can influnce data comping from another. A simple way is to give more hierachy to local data points as you move down the content flow of the site. For example, a configuration in the page level should over-ride what is in the layout level and what is in the layout level should override what is coming from the site level.
14. Schema or Data Validation
When it comes to list or text content, you need to be careful as one might pass in data that is too long for it's container and causing the layout to break. Further more in image fields, folks might add images in web formats that are not best pracise aligned e.g non-webp images. For which every case it's best you setup validations using tools like zod, yup, joi or custom code. Some things to validate in-code include:
- OG image format
- Image field file extension
- Title max/min text length
- Max list items count
- Preventing certain keyphrases in text content
- url, email or uuid type fields
15. Multipe CMS integration
If you understand content could be made up of text or data, you would also know that it can come from beyond markdown files. For markdown files, they can be edited locally and synced via Git or can also be edited via Github (Github is a kind of CMS, if you think of it). There are majorly 2 types of CMSs - Cloud based & Git based CMS. Which ever you should to adopt make sure they cather for the needs of the teams who use them. Some times every team might require a different CMS. A CMS could also provide not just, text but also layout content as HTML and styling files. It's up to you to sanitize and integrated content from your CMS.
16. Optimizations for Web Standards
From the start seek out the important web standards and keep an eye for updates to them. Some of these standards relate to performance, user experience, SEO and even how your site integrates with other services.
Integrations
Markdown extension
Post processing
- Validation
- Image optimization
- Typo checking
Don't fail to re-evaluate, refactor & refresh
a Algolia
Introduction
In the initial stages of my web development career, platforms like WordPress was all you need to setup marketing websites, but as web development standards like Pagespeed, SEO & performance become more directly connected to important metrics like conversion, page ranking and user experience, brands now demand are more native or light weight experience foroing the benefits of having a user-friendly drag and drop WordPress interface.
It seemed like before business, developers where the only ones who used statc sites for their blogs, documentation & project sites. Building websites was basically split between developer-friendly vs user-friendly approaches. While a lot of user friendly platforms like Webflow are catching up to provding very performant websites, some big brands prefer to spin up their own codebase for adminstering their sites statically.
Beyond the useful advancements from HTML to adopting various templating languages like pug, handlebars & workflow tooling like gulp, webpack, vite, there are other considerations or learnings from my experience build landing pages.
Learnings
1. Seperate Concerns
While we have the MVC - Model, View, Controller paradigm in web applications, I like to think of websites in terms of content, layout & media. Where content can be best described by looking at the structure of a basic markdown file which has an section for storing json like data as well as the rest for storing text content. Content basically influences how layouts would turn out and can include media assets in them.
So how seperation of concerns would usually turn out involves
- Detaching content from the layout and making them only editable via markdow file or CMS integrations.
- Layouts should be handled with reusablity & modularity in mind will taking into account how edge cases in content would affect it's outlook
- Media must be handled seperately as it goes beyond just including a link to a file to involve managing page load performance, pagespeed scores, best practises, affecting build times etc.
2. Make Site Configuration Accessible
It might seem obvious that the content team need access to those markdown files to publish content, but often times someone from another team or management might want to update the navigation themseleves, or the footer links or form id or even a javascript interaction. To save yourself some headaches or regular edits it's best you think of everything on the site as being configurable through content edit via markdown or CMS integration.
3. Access Management & Change Approval
What every tools you are using in your pipeline from updation of content to release, there needs to be a process for ensuring only approved content goes live, Github provides some good change approval checks and some CMS also incoporates this. You can use Git blame or activity logs of your CMS to know who changed what and when.
4. Deployment speed matters
Everyone might be fine with a 15min build time, until someday everyone wants to put some piece of content up in 3mins or take another down like yesterday. If the framework you are using has a massive build time, then consider switching, modern frameworks like Astrojs keep improving regularly. Some ways to ensure a faster build time include
- Add conditional build steps in your workflow manager, if you are using Github actions or Circle CI, you can include steps that can be skipped if need be
- Run some operations post-build e.g non-critical checks or checks that take too long can be setup to run immediatly after build and deployment is complete
- Avoid uncessary function calls in your static site setup, for example sending data to algolia all the time,
- Use caching, if you pull a lot of data from a CMS and it takes too long to download, you can as well store it locally or cache parts of it to save time
- Avoid having media files in the same project files, because they consume time uploading each time you deploy your project you can use services like Cloudinary or imgix to manage your files
- You can also setup some kind of selective deployment, that builds only content that is changed (should write about this in future)
5. Setup Thorough Observability
Do not assume to trust your code or setup, something can go wrong due to your own faults, negligence or sometimes totally unexpected from something attached to your process. Take note the more the pages and process you have the more the items to observe increase so I encourage you to adopt automation in your workflow early on. Some observability measures include.
- Collect JS errors using tools like sentry before they get reported by a user or team
- Track visual or text changes using tools like visual ping
- Tracking your critical or business flows using tools like New relic or cypress
- Add content/ data validation using tools like zod, joi and yup
- Setup compilance trackers that check regularly so you know when something is missing
- Monitor 3rd party services & apis you some, sometimes some of them change api structure which can end up breaking your layouts
- Monitor site uptime, domain name renewals or SSL using tools like uptime robot
6. Make content reusable everywhere
Looking into the information architecture of things, blog posts need to have a page as well as show up in the blog listing page. Futher more, we cloud want to include them on a banner in the footer or on a CTA somewhere. It would be silly and prone to errors if one has to edit the same content from multiple areas all the time, hence it is wise to consider the reusability of both list, object or text content in the site.
7. Think of extensibility from the start
I have noticed that sometimes, teams get stuck thinking about the best approach towards deploying a project or a new feature. Most times the excuse is that they want something great from start. My general rule is to setup a solid foundation when you can or scaffold something simple if it's taking too long and return to it later. Sometimes the client might encourage you even to take a simpler approach as it's no big deal, but be rest assured that it would some become a big deal so if possible setup your tasks or project in such a way that they are easily extensible later or would require least effort refactoring if need be. This is crutual especially where a lot of content depends on the structure of things from the start. For example, the author information for a blog post content is better setup as an array of authors in the frontmatter than just a single author. One can just use only the first author in the list if the site only just reuires one author per post. It would be easier to extend once a post can have mutiple authors. Further more instead of just providing an author id, you can provide a way to customize on-page/post information about the author. Some points on extensibility to think on include
- Compliance measures
- Multi-linugual support
- Service integrations
- Splitting, or migration
8. Leverage Automation
Automation is not negotiable as content & processes scales. You can get warn down if you keep out repitive tasks without considering alternatives. From time to time, take a break and ask yourself if this thing you do everyday can be automated away. One strong reason to leverage automation is to save you time so you can focus on more creative things that have impact. Automation is even more necessary in monitoring and securing the integrity of your site. Some examples of things to automate
- OG image
- Post thumbnail
- js yaml to update frontmatter of many markdown files
- Sitemap & RSS feed
- Content validations
- PageSpeed checks
- Broken links, images or 404 page checking
- Typo & lanugauge checking - basically tag the elements that needs typo checking on your page and use a service or script to check and report
- Image processing
- Data pipeline for reporting
9. Leverage data points
The frontmatter or data from CMS api usually have a field, value format which could be in a list or object format. These fields could be of various types like text, date, number which can be used to infer scale, order, identity etc. Sometimes they work in combination and sometimes their precense or absence can depit something is wrong
- Data fields can be used to setup reporting for stale content, filter out future content
- Do not provide an information twice e.g If slug can be the file name, then no need to provide it in the file again except perharps as an over-rides
- Use them in automations e.g Use post title in OG image generation
- Setup validations on them. For example character counts, list size etc.
10. Support the Teams with Libraries & Dashboards
Some additional setups are required sometimes to facilitate working with other times. For example site administrators might need a place to upload images, videos and pdfs. Sometimes to assure the designers on the project you are on the same page, you would need to share links that show records of all the styles or site sections adopted. When you have setup custom scripts for automation and reporting, you might need a user friendly dashboard to enable team members also trigger automations or export reports.
- Layout libraries
- Style guide
- Media libraries
- Reporting & Feature Dashboards
11. Don't Skip Dev Experience
If you are previlegdge to have other developers working with you on the team, it's best to constantly evaluate if things can be done better and suggest them or take them up. Sometimes might seem hard intially but they would save a lot of headaches in the future. Dont be afraid to setup your own tool or extend exisiting ones.
- Use typescript
- Setup validators
- Use prettier & ESlint
- Setup proper documentation
- Use Husky for pre-commit checks
- Leverage peer programming
- Use & extend packages, libraries and frameworks
12. Understand & Organize How Data Flows
Back to making a site more configurable, I usually take this approach of organizing by site -> layout -> page group -> page -> sections/ panels. Meaning any content from markdown or apis would come from a site level, trickle down fro the layout, page group down to the individual panels in a page. There are other ways of arranging this for example where there is no page grouping. I adopt page group so that I can apply similar configuration to pages found in that particular group.
13. Use overrides & defaults with concion
After understanding the flow of content through the site, you must also have an understanding of which destinations require a default value if non is provided and also how content from the various flow points can influnce data comping from another. A simple way is to give more hierachy to local data points as you move down the content flow of the site. For example, a configuration in the page level should over-ride what is in the layout level and what is in the layout level should override what is coming from the site level.
14. Schema or Data Validation
When it comes to list or text content, you need to be careful as one might pass in data that is too long for it's container and causing the layout to break. Further more in image fields, folks might add images in web formats that are not best pracise aligned e.g non-webp images. For which every case it's best you setup validations using tools like zod, yup, joi or custom code. Some things to validate in-code include:
- OG image format
- Image field file extension
- Title max/min text length
- Max list items count
- Preventing certain keyphrases in text content
- url, email or uuid type fields
15. Multipe CMS integration
If you understand content could be made up of text or data, you would also know that it can come from beyond markdown files. For markdown files, they can be edited locally and synced via Git or can also be edited via Github (Github is a kind of CMS, if you think of it). There are majorly 2 types of CMSs - Cloud based & Git based CMS. Which ever you should to adopt make sure they cather for the needs of the teams who use them. Some times every team might require a different CMS. A CMS could also provide not just, text but also layout content as HTML and styling files. It's up to you to sanitize and integrated content from your CMS.
16. Optimizations for Web Standards
From the start seek out the important web standards and keep an eye for updates to them. Some of these standards relate to performance, user experience, SEO and even how your site integrates with other services.
Integrations
Markdown extension
Post processing
- Validation
- Image optimization
- Typo checking
Don't fail to re-evaluate, refactor & refresh
a Algolia