DEV Community: Maciek Palmowski

How to easily start blogging as a developer

Maciek Palmowski — Wed, 10 Apr 2024 16:57:15 +0000

So, here you are - you have a great idea for an article or even just wrote it, but you must publish it somewhere. Here are some tips about starting your developer blog.

SaaS

Let's start with services that will do the most work for you. You only have to register and focus on writing.

While those are the quickest to start writing on, always remember that at some point they can change the rules and become paid or add some gatekeeping for readers.

dev.to

Dev.to is a service that allows you to start blogging in minutes. They focus on dev-related content, so you'll feel in a good place.

You have to create your posts using markdown (which I consider a good thing) and what's most important it's free.

You can customize your profile a bit, by setting branding colors.

Most important features:

free
you can export your articles if you would like to migrate it somewhere else
others can comment/react to your articles
you can't use your own domain

I like dev.to - unit I started writing regularly here, I was using it from time to time and I liked the experience. I consider this platform a great place to start and a great place to post copies of your articles from different sources.

dev.to admin panel

Hashnode

Hashnode is very similar to dev.to - it allows you to start blogging quickly and for free. The are some differences though. It has a more robust editor (but you can switch to basic markdown), allows you to use custom domains, and has a paid pro version that allows you to use AI and some other features.

Compared to dev.to you can customize it more. And it also has an amazing headless version, so you can bring your own front end.

Most important features:

can be used for free, but there is a paid version too
you can export your articles
others can comment/react to your articles
you can use your own domain

I like Hashnode too. It's really cool and it evolving quickly. Their headless feature is really cool too.

Hashnode admin panel

Medium

Some time ago I would also recommend Medium, but some of their practices like requiring readers to create accounts and pay for them each month are preventing me from doing so. In short - don't use it. Dev.to or Hashnode are much better.

Self-hosted solutions

Nothing describes them better than "with great power, comes great responsibility". You are responsible for hosting, security, and making sure your website works. That's not an easy task. On the other hand, you can customize the website as much as you want.

Astro and other SSGs

Time to enter the Static Site Generator zone. Personally, I recommend Astro, but there are many others like Eleventy, Nuxt, or Next. All of them allow you to write your content using Markdown.

The main advantage of using them is having full control over your data.

Also, most of them will give you access to a collection of templates that can be modified in a way you want.

Using them is one thing - you have to host it somewhere. Don't worry though - there are many places where you can host static sites for free like Vercel, Netlify, CloudlFlare, or GitHub Pages. And even if one will stop being free, it's very easy to migrate from one place to another.

Most important features:

it's free
you have full control over everything
you can extend it
things like comments or forms will require 3rd party tools
you'll need hosting

I'm a huge fan of SSG. And usually, I would recommend one of those. On the other hand, I saw too many cases when developers spent so much time customizing their blogs, that they forgot to write new articles.

Visual Code Studio and Astro

Statamic

It's time to enter the CMS territory. If you have a bit of experience with PHP, then Statamic might be a great solution for you. It has a few cool starter kits (so you can start writing right away), it's flat-file-based by default and it has an SSG library (so you can host it for free on Vercel or Netlify).

This is also the way I chose - this blog is created in Statamic. First I used a pre-made starter kit, and over time my wife created this cool look.

Most important features:

it's free for personal use
you have full control of everything
you can extend it
you'll need hosting

Statamic is one of my favorite CMSs out there. You can find some materials about it on this blog too. Highly recommend it if you know PHP basics.

Statamic admin panel

WordPress

With WP, you'll just need a bit more fuss to get it working exactly as you want - probably you'll need a code highlighter block and some other plugins to make everything as you imagined. While that's not a problem, you can do it quite quickly, the bigger problem is the database. The thing I loved so much about Statamic was the lack of it. The database adds some problems with moving stuff around from localhost to production (there are plugins that can help here).

Luckily there are also plugins helping to convert WP into a static website (Simply Static), so you can host WP for free on Netlify, Vercel etc.

Most important features:

it's free, but some plugins aren't
you have full control over everything
you can extend it
there is a plugin that allows you to convert it to a static website
you'll need hosting

WordPress admin panel

Time to sum up

If you want to start writing, select a solution that will allow you to start as soon as possible. That's why I would recommend going with Dev.to or Hashnode as they will allow you to start writing in a few minutes. After some time you can decide if they are right for you, or maybe they are limiting you somehow. In that case, you can pick something else.

Overall, writing is the most important, everything else is just useless fluff.

Front Matter CMS - a bit different approach to content management

Maciek Palmowski — Sun, 24 Sep 2023 11:19:38 +0000

If you like my content, subscribe to my newsletter.

When we think about a CMS, the first thing that comes to our mind is WordPress. And even if we aren't thinking about WP, we still see an admin panel somewhere on the internet.

There is also a group that will say that MarkDown and any editor are good enough for them. They are also right. It can be enough, but working with frontmatter inside MD files can be tedious.

But what if I tell you that there is a CMS that will transform your Visual Studio Code into a proper CMS with content and media management, taxonomies, and more? Say hello to Front Matter CMS.

If you prefer listening and watching rather than reading - together with Elio Struyf, we did an episode of Code and Coffee Show about Front Matter CMS:

Installation

Because FM CMS is a Visual Studio Code extension, you must install it first. You'll find two versions - the stable one and the beta one.

After installation, it's time to open a project that you want to use with Front Matter CMS. After doing so, press the FM icon in the sidebar and follow the instructions. At this point, the basic configuration is almost done.

Configuration

Sadly, Front Matter CMS can't guess some things. So, before going further, we have to polish the configuration file a bit.

Let's start with the field. Inside of your frontMatter.taxonomy.contentTypes part, you'll see that some fields are already created. You have to update this part to match the fields you'll need. In my case, I needed to add fields like this:

"fields": [
  {
    "title": "Title",
    "name": "title",
    "type": "string"
  },
  {
    "title": "Cover",
    "name": "image",
    "type": "image",
    "isPreviewImage": true
  },
  {
    "title": "Intro",
    "name": "intro",
    "type": "string"
  },
  {
    "title": "Author (use the one from src/content/author)",
    "name": "author",
    "type": "string"
  },
  {
    "title": "Publishing date",
    "name": "pubDate",
    "type": "datetime",
    "default": "September 13th, 2023",
    "isPublishDate": true,
    "dateFormat": "yyyy-MM-dd"
  },
  {
    "title": "Tag",
    "name": "tag",
    "type": "string"
  }
]

Most of it is pretty self-explanatory, but there are some more interesting bits:

isPreviewImage - It shows the image as a thumbnail in the Front Matter CMS dashboard
isPublishDate - This one helps FM CMS to sort posts by date
now - Now is a placeholder that sets the time and date to the moment when you created the post

For more information about the fields, I recommend checking this page.

In the case of my Astro theme, there are some extra details I had to add:

"name": "default",
"previewPath": "blog/",
"filePrefix": null,
"fileType": "mdx",

Without setting the previewPath, FM CMS would try to preview blog posts on domain.com/slug which would return a 404 error because all blog posts are in the blog folder. Adding this setting solves the problem.

By default, new files created by FM CMS contain a date as a part of a slug. This is something I'm not a fan of. Luckily, thanks to the filePrefix setting, we can change it.

And last but not least - I wanted to create MDX by default - that's why I used fileType setting.

Managing content

Like in any other CMS, you can view your content in the dashboard. Apart from this, you can group them (by year, for example), sort them, or search for a post you want.

When viewing a single post, you can access some new powerful features. There are some practical SEO tools or a preview option.

You can also manage images. View them, organize them in folders, and add metadata to every image - like alt texts or descriptions.

Snippets

Snippets are a fantastic way to stop repeating yourself. It works really great with MDX files and components. So, let's create a simple component that will show Hello [your name].

The simplest way would be to go to Snippets, press the Create new snippet button, and paste something like this:

import Hello from '../../components/hello.astro';
<Hello name="Test" />

and modify the code a bit every time. But we can do better. It's time to reopen our config file and add some fields.

"frontMatter.content.snippets": {
  "Hello": {
    "description": "A simple snippet",
    "body": [
      "import Hello from '../../components/hello.astro;'",
      "",
      "<Hello name=\"[[name]]\" />"
    ],
    "fields": [
      {
        "name": "name",
        "title": "Name",
        "type": "string",
        "default": "FM_SELECTED_TEXT"
      }
    ]
  }
},
"frontMatter.snippets.wrapper.enabled": false

This will result in:

But also, if you select a text and then add the snippet, the selected text will become a default value. Neat.

There is just one problem with this - there is no way to add a conditional to check if we should import the component again or not. This is something we have to remove manually every time.

For more use cases, check out the docs.

Custom scripts

One of the most powerful features of Front Matter CMS is the ability to create your own scripts that can do whatever you want. I will show you a very simple example of how to make your title uppercase with a click of a button.

This is the script we'll use - I placed it in the scripts folder:

const arguments = process.argv;

if (arguments && arguments.length > 0) {
  // getting all the frontmatter args
  const frontMatterArg = arguments[4];

  // transorming to json
  const data = frontMatterArg && typeof frontMatterArg === "string" ? JSON.parse(frontMatterArg) : null;

  // making the title uppercase
  const title = data.title.toUpperCase();

  // updating the contnet
  const output = JSON.stringify({
    "frontmatter": {
      "title": title
    }
  });

  console.log(output);
}

As you see - it gets the data, changes the title, and creates a JSON that is passed to console.log

Now, let's add this script to FM CMS. We have to open the configuration file again and add:

"frontMatter.custom.scripts": [
  {
    "title": "Uppercase title",
    "script": "./scripts/social-img.cjs",
  }
]

This will result in this cool-looking button that will uppercase your title.

Just press the "Uppercase title button"

But you can do more with custom scripts - check this documentation section to learn more about custom scripts.

Summary

I hope I showed you how cool Front Matter CMS can be. While it's not a CMS for everyone, I think that developers will find it very useful. Also, they won't have to leave their favorite IDE.

As for less technical people - if someone will configure it for them, FM CMS might be a really easy-to-use solution.

Different flavors of content management

Maciek Palmowski — Mon, 28 Aug 2023 13:40:20 +0000

Picking up a perfect CMS isn't an easy task. You have to consider many things before picking the one and only. Here is a small guide explaining the different aspects of every CMS.

Most people widely know the term Content Management System (or CMS for short). But many people don't see how many CMS flavors there are. I hope to list and explain the pros and cons of most possible approaches below.

Headless vs. Monolith

A monolith CMS is a CMS that is responsible both for managing data (you can create posts, add images, etc.) and for showing this data to others (using some templating system). WordPress, Statamic, CraftCMS, or Drupal are perfect examples of monolith CMSs (although all can go headless too).

A headless one is responsible only for data management and providing an API for other applications to show this data. When talking about headless CMS, Strapi or Sanity comes to my mind first, but there are many more.

So you know the theory, but when should you use them? Monolithic CMSs are usually simpler to use because you get everything working out of the box. On the downside, you have to use the tech in which the CMS is created (you'll use PHP for WordPress or Ruby for Camaleon).

On the other hand, headless CMSs start to shine when our setup gets a bit more complicated, or our development team would like to use a different technology than the one in which the CMS is created. The biggest cons? You'll have some additional work orchestrating everything.

You should also check my article about headless.

Self-hosted vs. SaaS

Another way in which you can differentiate CMSs is the way how they are hosted.

Self-hosted solutions give you complete control over your data. You can do everything with it. But with great power comes great responsibility - hosting, updates, backups, etc. If you mess something up, it's all on you. Also, you have to set everything up.

WordPress, Statamic, or CraftCMS are great examples of self-hosted solutions.

When you decide to go the SaaS route, in theory, the product should got you covered with all the backups and other responsibilities. You should only focus on your website. There are some potential downsides:

You might need a feature that your SaaS won't provide
The pricing may change
The company behind the SaaS might not fulfill its responsibilities, and you might learn you lost all your data.
They might sunset the product, and you'll have to move somewhere else quickly.

Webflow, Storyblok, and ButterCMS are great examples of SaaS CMSs.

Content editing vs. visual editing

Some CMSs only allow you to edit content placed somewhere inside premade themes or templates. The biggest pro of such a way is also its biggest con. With such an approach, there is a separation of concerns - the CMS is only responsible for the content, while how it is presented is totally on the template end. You have to ask the developer if you want a more significant change. On the other hand, if made correctly, it helps keep the website more consistent and prevents destroying the UX created by the team responsible for this.

Statamic, CraftCMS, and Strapi are perfect examples here.

With visual editing, you have much more flexibility. You aren't only capable of changing the content - you can also change the way everything is presented. This approach gives the user much more freedom, but such freedom can destroy the website's UX in the wrong hands. On the other hand, you won't have to ask the developer about every change.

WordPress (with Page Builders or Full Site Editing) or Storyblok are perfect examples in this category.

Remote vs. local

The most typical approach is having a CMS admin panel sit somewhere on the server; everyone with an account uses this. This is a very convenient approach, especially when working with a team. This way, many people can work on different articles simultaneously without worrying about potential conflicts or overwriting stuff. The only con is related to security - everyone can try to get inside, and if you forget to update our CMS or some user have a weak password, it can be someone outside of our team. WordPress, Drupal, CraftCMS, or Ghost are perfect examples of such CMSs.

Local CMSs are the ones that are mostly file-based (like Statamic or Astro). This means that you can edit everything locally and deploy the data. This way, our CMS is more secure, but on the downside, you have to have a local server working, and you might experience more conflicts, especially when two people will work on the same article (although Git might save you from many of those). It also means that there is a higher learning curve. A remote CMS works somewhere on a server, and most users don't care how.

Dedicated app vs. bring your own app

When discussing CMSs, the first thing that comes to mind is an admin panel, where you create and edit our content. And most CMSs work that way. Why? Because it is convenient and it's easier to teach your team how to use it. The only downside is that you have to get used to the admin panel, and sometimes you might not have any option to customize the experience.

But, when your CMS is based on Markdown files, you can use whatever editor you want. For example, if you use Nuxt as your CMS, everyone can choose which editor they prefer. It can be Visual Studio Code, FrontMatter CMS, or maybe Nuxt Studio. Everyone can pick the app they like the most.

WordPress vs. the rest

It might sound funny, but WordPress has ~60% of the CMS market share. Shopify is second with 6%. Here is the source of those numbers.

We might discuss the methodology and the fact that WordPress is easy to discover, while some CMSs aren't, but it doesn't change the fact that WP is playing a totally different game today. But we also have to remember that it wasn't like that.

I just found a report from 2008 where we can read:

At this point in time, the only thing we can state with confidence is that the battle for market dominance has yet to be settled. Indeed, it rather looks like the battle is just about to heat up! WordPress, Joomla! and Drupal share a significant lead over the other products in the open source CMS market. We do not expect that to change in the near to medium term. Whether one will emerge as the market leader remains to be seen.

Who knows what the market will look like 10 years from now?

Git-based vs. API-driven

Big thanks to David Large for mentioning this distinction for headless CMSs.

Git-based CMS are the ones that use Git to manage many aspects of CMS - mostly related to collaboration and history. This is a great solution because we aren't reinventing the wheel, but we're using an amazing standard for stuff like this.

Also, we have full control over our content.

Solutions like CloudCanon or TinaCMS use this approach.

API-driven CMSs provide you with an API that you have to connect with your front end. Those CMSs are very often more flexible. They are also great if we want to provide data to multiple sources (our website, store, and mobile application).

We can control our data (self-hosted solution like Strapi) or not (Contentful) based on the chosen solution.

Those CMSs, in most cases, are more difficult to start with and require a developer for any bigger change.

Site Builders vs. App Frameworks

Big thanks to Shaun Walker for mentioning this distinction.

It might seem that it is similar to Content editing vs. visual editing, but not completely. Content vs. Visual editing is more about how we edit the content. Here, we are looking more at the CMS's focus.

Site builders are solutions that should enable you to build websites without technical knowledge (in theory). They are amazing if your data structure is quite simple and you want a working website quickly. Those will be perfect if you want a landing page, a blog, a company page, or a simple store. Those solutions either have a lot of predefined blocks, or you can create everything manually.

There are some builders that are more customizable, enabling you to add your own components/blocks.

Webflow and Builder.io are perfect examples here.

App Frameworks are CMSs that can be extended in whatever way you want. If we take a look at what we can achieve with WordPress, Statamic, CraftCMS, or Drupal, we'll see that there are almost no limits. They are used for a personal blog but also can become a center of our very advanced application managing different parts of our business.

Summary

As I mentioned initially, picking up a perfect CMS isn't easy. Also, everything I said is just the tip of the iceberg. It's one of those "it depends" situations where you must analyze your needs and decide based on those.

Which CMSs I'm using right now?

I'm using Statamic for this blog - it's only on my local machine and converted to a static website during deployment. Why? It's a small blog, and I don't want to worry about security and other stuff.

I'm also using Substack (a SaaS) for my newsletter. Why? Because I'm lazy and I wanted to focus only on the content.

Did you enjoyed reading this post? If so, don't forget to subscribe to my newsletter.

Creating custom actions in Buddy

Maciek Palmowski — Mon, 02 Jan 2023 15:57:48 +0000

While Buddy was always my favorite CI/CD app, it was missing one feature - shareable custom actions. Luckily for us - it has changed lately and in this article, I will show you how to create them.

I always saw the lack of Custom Actions as the biggest downside of Buddy. There was an action Custom Build, but it didn't provide us with any UI options, and it was pretty tedious to share and keep updated.

Luckily, Custom Actions change all of this. From now, you can:

create a UI to make it easier to use
share it with others
import someone's actions

How to store Custom Actions

There are three ways to do so:

create a separate repository for all your custom actions
create a separate repository for each action
add actions to the project's repositories

Each is useful in some cases. A separate repository for all your actions is excellent when you work in a company and want to have all your actions in one place.

If you are considering an Open Source approach, having separate actions in separate repositories seems best.

But, if you want to create related actions with a project, then adding them to that project's repo is the best solution.

For more information, check out the official Buddy documentation.

How to create a Custom Action

Again, you have a choice. You can either create everything manually based on the documentation or use this small tool I made.

If you decide to use Buddy Custom Action CLI, you only need to run npx buddy-custom-action@latest and answer a few questions. When you are done, you should have a ready-to-use boilerplate.

Custom actions

Example #1 - No deployment on Friday action

Some time ago, I created this simple action that prevents deploying on Fridays. Let's try to convert it into a Custom Action.

First, I used the npx buddy-custom-action@latest. I only provided it with a name and a short description, and I said yes to creating an execute commands section.

    name: "no_deploys_on_friday"
    execute_commands:
      - 
    docker_image_name: "ubuntu"
    docker_image_tag: "latest"

This is my boilerplate. Of course, right now, it won't do anything. It's time to add the missing command itself:

    name: "no_deploys_on_friday"
    execute_commands:
      - if [[ $(date +%u) == 5 ]]; then echo 'Do not deploy on Firday.' && exit 1; fi;
    docker_image_name: "ubuntu"
    docker_image_tag: "latest"

Is this all? No - we should also add an icon and name it action.png

Now we are done. It was simple. Now it's time to create something more complicated.

You can download the code from this repository.

Example #2 - API Parser

This time, we'll create something more complicated. This action will get data from a given API then it will be parsed with jq and in the end, we will pass the result to another action.

Again, let's get started with running the npx buddy-custom-action@latest. We'll also need inputs and outputs this time.

Let's start with the inputs. Inputs are the fields that you can populate with some data. In our case, we will need the following:

the API URL
the jq command to filter out the required value

    inputs:
      url:
        name: "URL you want to test"
        required: true
      jq_command:
        name: "JQ parse command"
        required: true

I will use the Star Wars API and filter out the character's name.

Now it's time to add the exectute_commands:

    execute_commands:
      - apt-get update && apt-get install -y curl jq
      - api=`curl -s $url`
      - `jq $jq_command <<< $api`

It works - we will get Luke Skywalker as a result. But, while it works, this action is a bit useless. It would be much better to pass the result to other actions. Let's do it, then.

This is when outputs come in handy:

    output:
      variables:
        result:
          info: "Result of JQ on API"

This will result in a tiny change in how your action looks:

Now, we have to change the execute_commends too:

    execute_commands:
      - apt-get update && apt-get install -y curl jq
      - api=`curl -s $url`
      - result=`jq $jq_command <<< $api`
      - export result

From this point, we can use the result variable in other actions.

The whole action should look like this:

    name: "API_Parser"
    inputs:
      url:
        name: "URL you want to test"
        required: true
      jq_command:
        name: "JQ parse command"
        required: true
    output:
      variables:
        result:
          example: "Variable with the results of the JQ on API"
    execute_commands:
      - apt-get update && apt-get install -y curl jq
      - api=`curl -s $url`
      - result=`jq $jq_command <<< $api`
      - export result
    docker_image_name: "ubuntu"
    docker_image_tag: "latest"

You can download the code from this repository.

What else can you do?

The sky is the limit here. I see Custom Actions as one of the most groundbreaking features in Buddy, and it gives everyone the potential to create and share their own actions. We don't have to wait until developers have time to implement something - now, we can do it independently.

I can't wait to see what actions you will create.

Is it worth migrating from Revue to Substack?

Maciek Palmowski — Wed, 28 Dec 2022 11:50:13 +0000

As you probably already know, Revue is closing on 18 January 2023, and some of you are already looking for an alternative. I will try to explain if Substack is a good alternative.

When Elon Musk bought Twitter, there were a few rumors that Revue would be closed. So back then, I already started to look for an alternative.

In my case, I had a few requirements:

It shouldn't be too expensive.
It should be simple. I want to focus only on writing.
It should have the possibility to connect my own domain.
It should have a nice writing experience.
SaaS, I didn't want to manage anything.

Sounds simple, right? I was also surprised to learn that finding something like this is difficult.

After a week of testing, I decided to go with Substack. You can see the results of my hard work here.

Passing all the requirements

Pricing and my own domain

Substack can be free. You only pay if you have paid newsletters, but that's not my case. I only had to pull my credit card when I wanted to connect my domain. It was a one-time payment, and it was about $20.

Comparing the experience of connecting your domain in Revue and on Substack, I can say that paying those $20 was a pleasure.

Simplicity

While Substack has far more options than Revue, it's still straightforward. The migration process, setting up my theme, etc., was a breeze. I didn't have to use any extra documentation.

Writing experience

In general, Substack writing experience is really nice. The editor is quite zen and lets you focus on writing. One really cool thing is the set of premade blocks that can help you boost engagement.

There is one thing where Substack is losing with Revue - Revue has this great link block that downloads the open graph data.

Also, it would've been nice if Substack would support Markdown.

This is how the editor looks like

Migration

Migration was a fantastic experience. Why? Because it only took me about one hour, I never felt lost during the process. Keep in mind that this is the first time I was doing something serious on Substack, so I consider the amount of time needed very short.

It has a big flaw and one small one

Can you imagine that this almost perfect newsletter system lacks API? I'm not kidding. I learned about this when I wanted to automate something when I discovered this thing.

I was sure that all newsletter apps have at least a simple API. But not here. I probably understand why - Substack wants to be a place where you focus on writing, not where you send your corporate notifications for free.

Also, the statistics module could be better. It's not bad, but there is room for improvement.

Would I recommend moving to Substack?

It all depends if you need the API or not. If not, I think Substack is as closest to perfection as possible. I've been using it for 4 weeks, and I really like it. I really enjoy the moment when I'm preparing my weekly newsletter there.

What other applications did I check?

I started with big names like Mailchimp, MailerLite, and GetResponse - they are much better for corporate usage than a small, personal newsletter.

Buttondown - I loved the possibility of writing using markdown, but their free tier is kind of poor, and the UI was a bit too old-fashioned for me.

Beehiiv - it has a lot of features and a nice free tier, but it has too many options.

Newsletter Glue - NG is a WordPress plugin. It has everything I need, but I would have to host it on my own. If it weren't for Substack, I would probably install WordPress somewhere and install Newsletter Glue there.

Playing around with Sanity.io

Maciek Palmowski — Thu, 15 Dec 2022 09:24:07 +0000

Sanity.io is one of the new cool kids regarding headless CMSs. I decided to give it a try and create almost precisely the same blog as the one you are reading.

What is Sanity.io

First of all, Sanity.io is a headless CMS. This means it's only responsible for storing the data, and it's up to us to connect it with a front end. We can use whatever we want here.

The CMS is fully configurable. Thanks to Sanity Studio, we can configure our CMS how we want - we just need to create schemas.

Sanity also gives us two ways to communicate with our application: GraphQL or GROQ. I just want to say that GROQ quickly became my favorite. It's like SQL and GraphQL had a baby.

Now that we know what Sanity.io is, it's time to code.

The plan

I plan to create a blog like the one you are just reading. This means we will need the following:

posts
navigation menus
setting page
categories
pages (although I skipped this as even now I'm almost not using this)

There are also some things that I decided not to add because it's just an experiment:

SEO settings
Open Graph data
SSR

Time to start modeling this content using Sanity Studio

Installation and some groundwork

Installation is pretty simple. Just follow the steps from the official guide, and everything should be up and running in a few minutes.

In my case, I also installed one addon - the markdown input field.

And here is the code repository. In the studio folder, you'll find everything related to Sanity. Apart from this folder, everything else is associated with Astro.

Adding schemas

My schema structure looks like this:

schemas
|-- documents
|-- objects
index.js

The document folder is for post types, and the objects folder is for small bits that we will reuse from time to time.

For example, let me show you how to create a category schema. First, create an empty file category.js inside the schemas/documents folder. Then add this code inside:

export default {
    name: "category",
    type: "document",
    title: "Category",
    fields: [
        {
            name: "title",
            type: "string",
            title: "Title",
        },
        {
            name: "slug",
            type: "slug",
            title: "Slug",
            description:
                "Some frontends will require a slug to be set to be able to show the category",
            options: {
                source: "title",
                maxLength: 96,
            },
        },
    ],
};

As you can see, it consists of two fields - Title and Slug.

Next, it's time to import it the index.js file:

import category from "./documents/category";

export const schemaTypes = [category];

And is how our admin panel will look like:

You can browse the rest of the fields in the GitHub repo.

Connecting Sanity.io with Astro

Now, it's time to connect Sanity.io with Astro.

I won't go step-by-step because everything becomes simple if you understand how the GROQ language works.

First, we need to install the Sanity + Astro plugin. Kudos to Jaydan Urwin for all his hard work. After installing the plugin, I created a /src/utils/sanityHelper.js file to add all the helper functions I need.

So, let's get the navigation. First of all, I created a helper:

export async function getNavigation(navigationName) {
    const query = `*[_type == "nav" && id == "${navigationName}" ]`;
    const navigation = await useSanityClient().fetch(query);
    return navigation;
}

It fetches all the posts from the nav post type and the passed navigation id.

Next, in my header component I'm doing something like this:

---
import { getNavigation } from "../utils/sanityHelper.js";
const navigation = await getNavigation( 'header_menu' );
---
<ul class="font-bold font-palmiak-font tracking-widest">
{navigation[0].navItems.map((item) => (
    <MenuHeaderMobile href={item.navItemUrl.linkUrl}>{item.text}</MenuHeaderMobile>
))}
</ul>

... and that's it :)

Fetching posts is similar. There are some gotchas.

Images

In the helper file, you'll find the urlForImage function. To use, you have to use:

{urlForImage(post.mainImage).width(640).auto("format")}

Also, check the sanity/image-url documentation. You'll learn more about all its possibilities.

Markdown fields

Astro, by default, doesn't have any method to show markdown data that was fetched from an API. To fix this, we have you use the marked package. This is how I displayed post content:

---
import { marked } from 'marked';
const { post } = Astro.props as Props;
---
<div set:html={marked.parse(post.body)} />

Querying references

When I wanted to display category names in every post, I hit a small bump on the road. Luckly it was easy to solve.

This is what my initial query looked like:

*[_type == "post" ] {
    _id, 
    title, 
    publishedAt, 
    categories,
    mainImage, 
    excerpt,
    slug
} | order(publishedAt desc)

to get all the data related to each category, I had to add []->

*[_type == "post" ] {
    _id, 
    title, 
    publishedAt, 
    categories[]->,
    mainImage, 
    excerpt,
    slug
} | order(publishedAt desc)

Check out this page for more information.

That's it

I hope you'll also find Sanity.io as friendly and easy to use as me. Of course, this article just scratches the surface of what Sanity.io can do and how we can configure it.

Don't forget to share what you have done using Sanity.io.

The world outside of WordPress

Maciek Palmowski — Wed, 30 Nov 2022 02:17:43 +0000

WordPress has more than 40% of the CMS market share. But we are not alone in the IT world. There is a lot happening outside of WordPress.

My background

I was a PHP developer specializing in WordPress for most of my career. If you are following me on social media, you probably noticed that more than a year ago, I switched from development to DevRel. With this switch, I had to break out of the WordPress bubble. Don't get me wrong - I still love WordPress and most of the community behind it. But...

There is a world outside.

It's big and overwhelming and sometimes scary. But you know what? It's also fun, engaging, and very refreshing. Because I'm a DevRel, I don't have many chances to focus on something particular. Still, I'm having a lot of fun exploring different CMSs (like Statamic, Craft, or Sanity), new approaches (at last, I understood why the headless approach is so important), and diving into tech I never used before (hello Buildpacks).

Of course, this new world is also full of dramas, but it's a great place to learn something new. To compare how others lead their projects, work as a community, and deal with problems.

I can't wait for 2023, when I'm planning to visit quite a few conferences - most of them will be non-WordPress. This will also be refreshing to see them and compare them with WordCamps.

And this is something I would advise every developer - be like a tourist, visit new places and learn about different cultures. There is nothing more valuable than learning from others.

Where is WordPress heading?

It's pretty hard to say. We love to hide behind our market share because if we have 40% of the market, everything is great, right?

Recently, Jean Galea wrote a fantastic article that sums up most of the biggest problems in the WordPress space. When we put everything in one place, we can see WordPress space as a bit dysfunctional.

It's also worth mentioning that some companies, always seen as 100% WordPress, are looking for an additional income source. Just look at Yoast with their Shopify plugin or Kinsta with their Application and Database hosting. I think that it's a very healthy approach. Such an approach gives them much more stability in case the WordPress market changes.

On the other hand, from the developer's perspective, WordPress is often seen as either legacy or boring. This makes it more challenging to find new talents interested in contributing to WordPress. For sure many of them will pick something related to Laravel or Jamstack.

What will I do in the future?

As I mentioned, switching to DevRel and breaking out of the WordPress bubble was one of the best things that happened to me. WordPress did several things really great, but it also made some mistakes. Looking at this with an open mind and from multiple perspectives is very interesting.

That's why I see my future in DevRel. It gives me much freedom to observe the IT world without closing myself in a bubble again.

Is going headless worth the fuss?

Maciek Palmowski — Tue, 08 Nov 2022 09:00:41 +0000

Headless is one of the buzzwords that we keep hearing around. Very often it's described as something that will change our world, make the birds sing, and let the sun shine.

I was always a bit skeptical about headless, and I disagreed with the most popular pros of such an approach. I always saw headless as a waste of time or an excuse to play with new shiny toys. But things change, and more and more, I'm leaning towards the headless approach.

Why I didn't become a fan of headless from day one?

In the WordPress world, the term "headless" became popular primarily thanks to GatsbyJS. Suddenly everyone started converting their websites to Gatsby and tweeted about how fast they had become.

The speed argument was the one that always annoyed me. Some of those devs didn't understand that they just saved their WP site as static HTML. It's challenging to have a slowly working HTML. Especially since WP already had multiple solutions to convert a website to static or to cache it (which works almost the same). Also, I know how to optimize a website, so in my case, Gatsby always had a worse PageSpeed score.

Another popular argument was the one about how unique components are. Of course, but include in PHP works similarly (at some level).

In the end, "headless" annoyed me as hell, but I knew it was here to stay.

What changed?

First of all, Astro happened. Astro was the first Jamstack SSG I liked, and it helped me understand many concepts of Jamstack. It's simple and easy to learn.

Also, WordPress is pushing more toward the low-code/no-code direction. This caused my bigger interest in what is happening outside of WordPress. That's also the reason why this blog is created with Statamic.

And what's most important, I understood that headless can give us much more freedom. I like using WordPress as a CMS, but I don't like the direction in which the rest is going (block themes, Full Site Editing, etc.). Until some point, I tried not to care, but lately, I started to feel that I was fighting against the modern WordPress vision.

I even had a talk about this with Filip Rakowski

Off goes the head

Some would say - just change the CMS. But CMS is something more than just a toy for developers. In many cases, CMS is the workplace for marketing teams. We can't just change it when we find a new one (even if the new one is technically superior). On the other hand - our clients don't care which CMS we use. The whole front-end experience is what matters to them.

That's why going headless is an excellent way to:

keep the CMS which our team loves
separate the front-end
and very often hide the rotten core under the layer of new paint

Headless will also give us more flexibility in case of changing the technology underneath. We are no longer glued to a specific technology like in a monolith approach.

There are tradeoffs

Of course, headless also has its tradeoffs. You aren't maintaining one codebase that does everything, but at least two (the CMS and the front-end). Also, there is a big chance that developing a headless website will be more expensive.

And let's not forget that it will be a bit more complicated:

How the front-end will know when to rebuild itself after publishing new content?
How to orchestrate the builds and deployments?
How to take care of live-previews

So, before going headless, think about if you really need it.

Implementing Astro live previews in headless Statamic

Maciek Palmowski — Tue, 25 Oct 2022 18:34:53 +0000

Using Astro with different headless CMSs is excellent and relatively easy to achieve. The only problem is dealing with the live previews.

I already wrote an article about this for Buddy on using headless Statamic. If you want to learn a thing or two about head there first.

Why it's a problem?

Astro, by default, is a Static Site Generator, which means that every time we change something in our content, we must rebuild the whole website. And this would mean waiting for each change.

Server Side Rendering to the rescue

Astro introduced SSR some time ago and using this, we can create previews (and many other cool things) without rebuilding everything. We'll just need one extra server where SSR will work (e.g., Netlify).

Also, it's worth mentioning that we can use a similar method not only for Astro but also for other Jamstack frameworks that have the option to use SSR.

Let's imagine that our page looks like this:

---
const API_URL = 'YOUR_DOMAIN';
let post = {};

export async function getStaticPaths() {

    const res = await fetch( `${API_URL}/collections/pages/entries/` );
    const posts = res.json();
    return posts.data.map((post) => {
        return {
            params: { slug: post.slug },
            props: { post } };
        }
    );
}

const {post} = Astro.props;
---
<html>
    <head>
        <title>{post.title}</title>
    </head>

    <body>
        <main>
            <article>
                <h1>{post.title}</h1>
                <div set:html={post.content}></div>
            </article>
        </main>
    </body>
</html>

Simple, right?

Let's add some simple SSR:

---
const API_URL = `YOUR DOMAIN`;
//let's store is_preview as an environmental variable
const is_preview = import.meta.env.PREVIEW;
let post = {};

export async function getStaticPaths() {
    const res = await fetch( `${API_URL}/collections/pages/entries/` );
   const posts = res.json();
    return posts.data.map((post) => {
        return {
            params: { slug: post.slug },
            props: { post } };
        }
    );
}

// if true - SSR
if ( is_preview ) {
    post = await fetch( `${API_URL}/collections/pages/entries/` + `${Astro.params.slug}` );
    const res = await post.json();
    post = await res.data;
} else {
    const {post} = Astro.props;
}
---

<html>
    <head>
        <title>{post.title}</title>
    </head>

    <body>
        <main>
            <article>
                <h1>{post.title}</h1>
                <div set:html={post.content}></div>
            </article>
        </main>
    </body>
</html>

Let's take a look at what happened here.

First of all, we add is_preview, thanks to setting it as true or false, we'll be able to populate data with correct values.

Also, it's essential to know that getStaticPaths is ignored when running in SSR mode.

Looks ok? More or less - time to go to Statamic.

Live previews in Statamic

Statamic has a cool feature that lets us change the URL of the live preview. Go to this page to learn more.

So, in our case, we should just set our link to our server with SSR enabled (for example, Netlify).

It's also worth mentioning that Statamic adds two extra parameters to the URL live-preview and token. Thanks to them, Statamic can deal with non-saved data.

So, after connecting everything, we can see that... the data doesn't refresh.

Why? Because we forgot about passing the live-preview and token parameters. The fix is straightforward:

---
const API_URL = 'YOUR DOMAIN';
const is_preview = import.meta.env.PREVIEW;
let post = {};

export async function getStaticPaths() {
    const res = await fetch( `${API_URL}/collections/pages/entries/` );
    const posts = res.json();
    return posts.data.map((post) => {
        return {
            params: { slug: post.slug },
            props: { post } };
        }
    );
}

if ( is_preview ) {
    const url = new URL(Astro.request.url);
    const params = new URLSearchParams(url.search);

    post = await fetch( `${API_URL}/collections/pages/entries/` + `${Astro.params.slug}` + '?token=' + `${params.get('token')}` + '&live-preview=' + `${params.get('live-preview')}` );
    const res = await post.json();
    post = await res.data;
} else {
    const {post} = Astro.props;

}
---
<html>
    <head>
        <title>{post.title}</title>
    </head>

    <body>
        <main>
            <article>
                <h1 >{post.title}</h1>
                <div set:html={post.content}></div>
            </article>
        </main>
    </body>
</html>

Now, everything should work.

What should the final setup look like?

In my case, it looks like this:

Server with Statamic
One Netlify account where I have the final static version of the website
One more free Netlify account where I have the SSR version
And, of course, Buddy to automate all of this.

Did you liked the article?

If you liked the article and would like to read more - Subscribe to my newsletter.

Easiest way for Gutenberg Blocks with Timber and ACF Blocks

Maciek Palmowski — Thu, 06 Feb 2020 09:59:23 +0000

Some time ago I wrote the official Timber Documentation on ACF Blocks. Now I’ll show you how to do it in a much easier manner.

Preparations

Before we start we need to do three things:

Install Advanced Custom Fields PRO
Install Timber ACF WP Blocks library
Create a views/blocks folder in your theme

The best way to install the mentioned library is of course via Composer.

In case you don’t like the views/blocks folder you can change it by using timber/acf-gutenberg-blocks-templates filter.

Time to create a block

In our views/blocks folder we create a twig file (in this example — owl-link.twig) and on top of it, we add some additional comments. This Comment block is very important because thanks to it the block is registered and the values go to acf_register_block_type.

{#
  Title: Owl link
  Description: Link block
  Category: formatting
  Icon: admin-comments
  Keywords: link links
  Mode: edit
  Align: left
  PostTypes: page post
  SupportsAlign: left right
  SupportsMode: false
  SupportsMultiple: true
#}

<section class="gutenberg-wordpressowka-block">
    <div class="gutenberg-url-block">
        {{ fields.opis }}
        <a href="{{ fields.link.url }}" target="_blank">{{ fields.link.title }}</a>
    </div>
</section>

Of course, we can use all the parameters specified in the official ACF Documentation.

The only thing that missing is setting one thing in ACF itself:

Let’s use it

After registering and connecting our block there is one thing left — let’s write something:

Let’s sum up everything

As you see this is a very short article. Using Timber ACF WP Blocks lets you focus on blocks itself instead of creating boring code :)

If you would like to use this solution for Blade and Sage 9 use this plugin.

Timber - 4 reasons to love it

Maciek Palmowski — Thu, 23 Jan 2020 23:10:21 +0000

More than a year ago - Timber has become one of the basic tools I use in every WordPress based project. Here I'll try to show you why.

Timber - what is it?

The most basic definition would be that it's just Twig for WordPress. But that's not entirely true. Timber also adds many cool features like integrations with plugins (ACF, co-authors or WooCommerce) and filters for easy image resizing and manipulation.
At this moment it's available as plugin or library, but soon we'll drop the plugin support.

It brings order to your code

When you use Timber you have to separate logic from the view. Thanks to this we're avoiding WordPress's spaghetti coding like this:

<div class="wrapper">
<?php
$args = [ 'posts_per_page' => 3, 'post_type' => 'post' ];
$posts = get_posts( $args );

if ( $posts ) {
  echo '<div id="posts">';
  foreach( $wpisy as $post ) {
    $post = setup_postdata();
    echo '<p><a href="'. get_the_permalink().'">'.get_the_title().'</a></p>';
  }
  echo '</div>';
}

$args = [ 'posts_per_page' => 3, 'post_type' => 'page' ];
$pages = get_posts( $args );

if ( $pages ) {
  echo '<div id="strony">';
  foreach( $pages as $post ) {
    $post = setup_postdata();
    echo '<p><a href="'. get_the_permalink().'">'.get_the_title().'</a></p>';
  }
  echo '</div>';
}
?>
</div>

Of course, we can be sure that in real life this code would be much more complicated and less readable.

With Timber it would look like this:
archive.php

<?php
$context = Timber::get_context();

$args = [ 'posts_per_page' => 3, 'post_type' => 'post' ];
$context['posts'] = Timber::get_posts( $args );

$args = [ 'posts_per_page' => 3, 'post_type' => 'page' ];
$context['pages'] = Timber::get_posts( $args );

Timber::render( 'views/archive.twig', $context );

archive.twig

<div class="wrapper">
{% if posts %}
  <div id="posts">
  {% for post in posts %}
    <p><a href="{{ post.link }}">{{ post.title }}</a></p>
  {% endfor %}
  </div>
{% endif %}

{% if pages %}
  <div id="pages">
  {% for post in pages %}
    <p><a href="{{ post.link }}">{{ post.title }}</a></p>
  {% endfor %}
  </div>
{% endif %}
</div>

As you see - it's much easier to read. Also, it's easier in terms of using brackets and curly brackets. I always had some problems in PHP + HTML in some situations.

It has a great Advanced Custom Fields Integration

I love ACF with all my heart but with Timber, I loved it much more:

In every example, the Timber version is a bit shorter and more readable.

// Normal input
// without Timber
<?php the_field( 'nazwa' ); ?>

// with Timber
{{ post.meta('nazwa') }}

// Image
// without Timber
$img = wp_get_attachment_image_src( get_field( 'image' ), 'large' );
echo $img[0];

// without Timber
{{ Image( post.image ).src( 'large' ) }}

// Repeater
// without Timber
if( have_rows('repeater_field_name') ):
    while ( have_rows('repeater_field_name') ) : 
        the_row();
        the_sub_field('sub_field_name');
    endwhile;
endif;

// with Timber
{% if post.meta( 'repeater_field_name' ) %}
  {% for field in post.meta( 'repeater_field_name' ) %}
    {{ field.sub_field_name }}
  {% endfor %}
{% endif %}

Images

Earlier I mentioned about image filters for resizing and manipulation. Now it's time to take a closer look at them.
First of all - resizing:

{{ Image( post.image ).src | resize( 400, 400 ) }}

With this one line we get a 400x400px image.
We can of course use image sizes defined by WordPress:

{{ Image( post.image ).src( 'medium' ) }}

If we would like to generate few images for srcset we can do this with this code:

<img src="{{ Image( post.image ).src | resize( 400, 400 ) }}"
 srcset="{{ Image( post.image ).src | resize( 400, 400 ) }} 1x,
 {{ Image( post.image ).src | resize( 800, 800 ) }} 2x">

If you would like to learn more - check the documentation.

Twig Filters

What I really hate about PHP is the moment when I have to use multiple functions on one variable. For example:

first, we want to remove spaces with trim()
next change '-' to '_' with str_replace
and make a hash of it with md5

We can do it in two ways:

<?php
$foo = ' some variable';

// multiple bracket version
$foo = md5( str_replace( ' ', '-', trim( $foo ) ) );

// multiple line version
$foo = trim( $foo );
$foo = str_replace( ' ', '-', $foo );
$foo = md5( $foo );

In most cases I forget about some bracket or it takes three lines. With Timber, it's much easier. First I have to create one extra filter thought:

<?php
// functions.php
add_filter('timber/twig', 'add_to_twig');
function add_to_twig( $twig ) {
    $twig->addFilter( new \Twig\TwigFilter( 'md5', function( $text ){
        return md5( $text );
    } ) );
    return $twig;
}
?>

// our phrase
{{ foo | trim | replace({ ' ', '-' }) | md5 }}

Conclusion

I hope that those examples have shown how much Timber can simplify the WordPress code. Personally, it really made me like WordPress even more. I hope you'll give Timber a try.

Have you tried Timber or any other templating system (for example Blade)?