Local development using the command line

For me, as a beginner, by far the most challenging stage of building my website with Kirby and TailwindCSS, has been using the command line to set up my local development environment.

So I’ve written a blog post, detailing all the steps I took: How to set up local development for Kirby and Tailwind, using the command-line on macOS.

I hope my step-by-step guide might be helpful to any other Kirby users who’ve also been intimidated by this complicated process.

I’m not sure if there are many other beginners on this forum, so I’d appreciate feedback especially from anyone who finds my post useful, or who can suggest improvements.

I’d also appreciate feedback from any command-line experts who can correct my (hopefully not too many) errors.

Many thanks in advance!


Thanks for sharing, @brianliddell.

I really wanted to read up on this one since the headline suggested there was a simpler way. Then I saw that you struggled with CodeKit and Mamp, which are fairly strait forward. Then I started reading down your documentation which was really helpful but then noticed how much directions you have and thought “wait, all of this compared to CodeKit and Mamp?”.

I think I had already explored about 60% of the steps you’ve taken and went the valet and composer routes, but when working with others on Kirby projects, they preferred a more simpler approach without composer. So, clearly in my case it depends on who you work with or what you/your client are comfortable with. That’s how it goes. :wink: :man_shrugging:

It could be an old school thing, since I’m old, but my feedback is that those are a lot of steps for the kind of person who is afraid of CL (seems to me).

On the other hand, it looks like you’ve really done your research, you’ve documented it brilliantly, shown the potential pitfalls and how to avoid them, and… moved from Statamic to Kirby, so it’s hard to say you’ve gone wrong at all.

In fact, I struggled a bit going down those roads and I’m very happy to see someone pave the way for newcomers, so thank you for this!

Great work, Brian!

Update: I read through all of your instructions again. You’ve done a ton of work compiling this info. I wanted to be clear that it is very helpful. So, thank you, again.

@luxuryluke and @texnixe
Thanks for your nice comments!

Of course, you are absolutely right — the command-line approach is longer, and more complicated, than using CodeKit and MAMP. A much bigger project than I expected.

So, why did I use the command-line? The only reasons I can think of are:

  1. I wanted to try out Tailwind, and the command-line was the only way I could find to run the essential ‘purging’ process for this innovative new CSS framework.

  2. As a beginner, I found both CodeKit and MAMP confusing. I could get them to work, but I didn’t always understand what they were doing. This might seem surprising, but I think it’s an example of how difficult it is to write technical documentation for beginners.

This raises an important question: are Kirby, Tailwind, CodeKit, or MAMP actually intended for beginners like me, who only know HTML and CSS?

1 Like

CodeKit and MAMP are definitely intended (also) for beginners. At least the basic version of MAMP is easy to use, the MAMP Pro version can be a bit overwhelming.

Kirby/PHP is fine if – apart from getting a job or a website just done somehow – you also also willing to invest some time into learning something new. The fact that you have taken the trouble to write this tutorial tells me that you don’t give up easily. That’s great and we are always here to help.

Tailwind: Why not? If you have a basic understanding of HTML/CSS. I think that’s more a philosophical question. If you feel good with using utility classes then go ahead.

Sure, too many new things at the same time are sometimes hard to digest…

Keep going!

1 Like

I installed kirby and tailwind using brian’s tutorial. Would this then prevent one from using markdown? It is no longer rendering correctly.

No, not necessarily. Although you cannot easily add custom classes to content generated through markdown.

What exactly does not render correctly and what is the problem?

The markdown syntax is not rendering
none of the line spacing, bold, itlaics, bullets etc

What sort of field types are you using in your blueprints and how are you trying to render them?

I did not make any changes from plainkit.

title: Default Page
preset: page
    label: Text
    type: textarea
    size: large

Not sure if this could be the issue. I seem to be having an error parsing the JSON that I cannot seem to debug. I pasted the JSON and the log

“name”: “PlainKit”,
“version”: “1.0.0”,
“description”: “<img src=“http://getkirby.com/assets/images/github/plainkit.jpg” width=“300”>”,
“main”: “index.js”,
“scripts”: {
“build”: “postcss site/stylesheets/main.css -o assets/style.css”,
“keywords”: [],
“author”: “”,
“license”: “ISC”,
“dependencies”: {
@tailwindcss/typography”: “^0.4.0”,
“autoprefixer”: “^10.2.1”,
“postcss-cli”: “^8.3.1”,
“postcss-nesting”: “^7.0.1”,
“tailwindcss”: “^2.0.2”,

0 info it worked if it ends with ok
1 verbose cli [ ‘/usr/local/bin/node’, ‘/usr/local/bin/npm’, ‘run’, ‘build’ ]
2 info using npm@6.14.11
3 info using node@v12.18.0
4 verbose stack Error: Failed to parse json
4 verbose stack Unexpected token } in JSON at position 536 while parsing near '…ndcss": “^2.0.2”,
4 verbose stack }
4 verbose stack }
4 verbose stack ’
4 verbose stack at parseError (/usr/local/lib/node_modules/npm/node_modules/read-package-json/read-json.js:470:11)
4 verbose stack at parseJson (/usr/local/lib/node_modules/npm/node_modules/read-package-json/read-json.js:105:26)
4 verbose stack at /usr/local/lib/node_modules/npm/node_modules/read-package-json/read-json.js:52:5
4 verbose stack at /usr/local/lib/node_modules/npm/node_modules/graceful-fs/graceful-fs.js:123:16
4 verbose stack at FSReqCallback.readFileAfterClose [as oncomplete] (internal/fs/read_file_context.js:63:3)
5 verbose cwd /Users/patbass/My Sites/DND-Kirby
6 verbose Darwin 19.6.0
7 verbose argv “/usr/local/bin/node” “/usr/local/bin/npm” “run” “build”
8 verbose node v12.18.0
9 verbose npm v6.14.11
10 error code EJSONPARSE
11 error file /Users/patbass/My Sites/DND-Kirby/package.json
12 error JSON.parse Failed to parse json
12 error JSON.parse Unexpected token } in JSON at position 536 while parsing near '…ndcss": “^2.0.2”,
12 error JSON.parse }
12 error JSON.parse }
12 error JSON.parse ’
13 error JSON.parse Failed to parse package.json data.
13 error JSON.parse package.json must be actual JSON, not just JavaScript.
14 verbose exit [ 1, true ]

I have no idea what’s going wrong here, but let me say this:

Tailwind is a CSS framework and as such has nothing to do with Markdown or how Kirby renders it (because that happens server-side). Since I’m not a Tailwind user myself (tested it once briefly, but that was about it), I can’t tell what this issue might be, but this seems to be rather a problem with the Tailwind setup.

So what exactly is your setup? Did you follow @brianliddell tutorial?


I’m still a beginner with this stuff, so I might not be the best person to advise here!

However, the most likely reason for your problems, and a misunderstanding I also had when I started with Tailwind, is that this CSS utility framework doesn’t actually work within the Markdown field!

Tailwind is incredibly useful for rapid prototyping of the structure and layout of your website, but it does nothing to HTML output from a Markdown field. In fact, one of Tailwind’s key features is that it comes with no pre-set typography at all. So all the type styling has to be built up from a zero base, rather than hacking it down from the framework’s pre-set defaults.

The good news is that since I wrote my ‘Beginner’s Guide’ post, Tailwind has added a first-party Typography plugin which adds “sensible typography styles to any vanilla HTML”. There are good instructions for installing this plugin, and using its default styles, in the plugin’s Read Me file.

However, customising these ‘sensible’ styles seems quite complex (and intimidating) to me, and to some degree I think this defeats Tailwind’s original USP. But if you’re happy with Tailwind’s default typography styles, this is a super-simple way to go.

There’s an excellent demo and explanation for all of the above in Tailwind’s ‘Live Demo’ page.

The alternative approach, and the one that I’ve been experimenting with during these many months of coronavirus lockdown, is to write a custom stylesheet to target the HTML elements rendered by the Markdown field. There are good instructions for this in Tailwind’s docs, Extracting Components, in the ‘Extracting component classes with @apply’ section.

Typically, this means writing nested CSS that looks something like this:

/* default spacing */
.markdown {
   & > * {
     @apply mt-2;
     @screen sm {
       @apply mt-4;
/* over-ride for headings */
.markdown {
  & > h1,
  & > h2,
  & > h3 {
    @apply mt-6;
    @screen sm {
      @apply mt-9;

Since I started out with Kirby because I loved the simplicity and power of its Markdown field and KirbyTags, I’ve persevered with this approach.

And I’m super-happy with what I’ve been able to achieve by Pushing the limits of Markdown and just one image KirbyTag.

But it’s taken me months of experimentation, and I’ve ended up with a large custom stylesheet that’s miles away from the simplicity I’d expected from Tailwind.

I hope this helps!