This is part five, the last one, of a series teaching Clojure to people with little or no programming experience. In Part 4 you built a page that responds to what a visitor types.
In this part we'll create a simple blog.
The plan
To build the blog we need to:
- List the files in a
posts/folder. - Convert their format (Markdown) into HTML.
- Read one specific file when someone asks for it.
Step 1: Write two posts
Create a folder called posts in the root of your project (next to deps.edn, not inside src).
Inside it create two plain-text files.
posts/hello-world.md:
posts/second-post.md:
Markdown is a way of writing formatted text with plain characters: # at the start of a line means "big heading" and ## means "smaller heading". There is more you can do with Markdown, but don't worry about it for now.
Step 2: List the files
Let's explore this in the REPL. If the REPL from Part 4 is still open, you can use it. If not, open a new terminal (Terminal > New Terminal), run clojure, and wait for the user=> prompt.
Before we start, create a third file called posts/notes.txt. It can be empty. It's there to show why we'll need a filter in a minute.
First, tell the REPL which tools we'll use.
Now let's list the files in the posts folder:
Read it from the inside out:
(io/file "posts")points to thepostsfolder..listFilesasks a folder for what's in it, and.getNameasks a file for its name.#(... %)is a function without a name.%is the thing it receives, which here is one file.mapruns a function on every item in a list and gives back a new list with the results. Here it turns a list of files into a list of names.
(The names might come in a different order on your computer.)
We only want posts, and notes.txt isn't one.
Use the filter function to filter non-posts out. Also use the str/ends-with? function to keep only the files that end with .md.
Let's wrap filter around what we have:
notes.txt is gone.
It works, but look at how it reads. The first thing that happens (listing the files) is buried in the middle, and the last thing (filter) is at the front.
To understand it you have to start at the innermost line and read your way out.
Clojure has a solution for making this kind of code easier to read: threading macros.
(Think of "threading" as passing a value through a series of steps, like a thread through beads.)
The one we need is called thread last and is written ->>. It takes a value and passes it through the steps, adding the result of each step as the last item of the next one.
Here is the same code, written with it:
Same result, much easier to read. Adding more steps is also easier, just add another line at the bottom.
The page we build next will link to each post. If we use the full file name we would get something like /blog/hello-world.md. Let's remove the .md from the names. Try it on one name first:
#"\.md$" is a regular expression (regex for short), a pattern for matching text. This one means ".md, at the very end of the text".
What's left, hello-world, is the slug: the part of the address that identifies a post.
Now add that to the previous function. Let's also sort our list:
(sort has no parentheses because it needs nothing besides the list. When a step is just a name, ->> reads it as (sort the-previous-result).)
Now that we know it works, let's add it to our website. You can delete posts/notes.txt now. It was only for the experiment.
Update the ns at the top of src/app/core.clj. The only new line is [clojure.java.io :as io]:
Then add this above handler:
It's what we just tried in the REPL, wrapped in a function so we can call it by name.
def gives a name to a value (here, the folder name), so if we ever rename the folder we only change it in one place.
Save the file, then load it in the REPL and call the function:
Step 3: Build a page that lists them
This is just another function in the same shape as home-page and about-page. Add it above handler:
Two things are new:
forgoes through the slugs and makes one<li>with a link for each of them.str/joinglues the items of a list into one piece of text, with whatever you give it first (here"", nothing) between them.
Add a route to handler, before the 404 at the end:
And add a link to the new page in the navigation bar. In page, change the <nav> line to:
Save the file, then reload and restart in the REPL: (require 'app.core :reload) (app.core/start-server).
Visit http://localhost:8080/blog, and you should see your two posts listed.
Create a temporary file called posts/test.md (it can be empty), refresh, and it appears in the list. You didn't touch the code, and you didn't even restart: list-posts looks in the folder every time someone visits.
That's the idea of this whole part. Delete test.md again when you're done: we'll add a real third post at the end.
The links go to pages that don't exist yet. Let's fix that.
Step 4: Escape the text
Before we turn Markdown into HTML, we need a helper.
A post is just text, and some characters mean something special to HTML.
If a post says use <h1> for a big heading, the browser reads <h1> as a real tag: it disappears from the sentence, and everything after it turns into one big heading.
Escaping swaps those characters for safe versions: < becomes <, and the browser shows it as <.
We are building this escape function by hand for our educational purposes. In a "real" project you would likely use an existing library to do this.
Add this above handler:
->(aka thread first) is another threading macro, the cousin of->>. It also passes a value through a series of steps, but it puts the value first, right after the function's name, instead of last.- That's where
str/replacewants its text, so(str/replace "&" "&")becomes(str/replace s "&" "&"). - The text goes through four replacements, one after another.
- The
&goes first because the other replacements create&characters of their own, and we don't want to escape those a second time. - The last one,
"\"", is a double quote escaped with a backslash.
Save the file and try it in the REPL:
Step 5: Turn Markdown into HTML
Now the converter. It only understands what our posts use: headings, blank lines and paragraphs.
We'll also write a function that finds a post's title.
Add these above handler, below escape-html:
markdown->html goes through the post one line at a time:
str/split-linescuts the text into a list of lines,forgoes through them, andstr/joinglues the results back together with a new line ("\n") between them.condis likecase, but instead of comparing to values it tries each test in order and uses the first one that's true.:elseis just a test that is always true, so it works as a default.(subs line 2)means "linewithout its first 2 characters", which drops the#and keeps the rest. For##we drop 3.- Every piece of text from the post goes through
escape-htmlbefore it's wrapped in a tag. The tags are ours, and the text in between is the post's.
post-title looks for the line that holds the post's title:
filterkeeps the lines that start with#, andfirsttakes the first of them, ornilif there are none.if-letiswhen-letwith an "otherwise" branch: if a heading was found, it gets the nameheadingand the first result is used. If not, the second result,"Untitled", is used.
Save the file and try them in the REPL, with a line that has characters HTML cares about:
Step 6: Read one post
Add these above handler:
whenruns its body only if the test is true. It's the opposite ofwhen-not. If the file isn't there,read-postgives backnil.slurpreads a whole file into text.- The title goes through
escape-htmltoo, becausepageputs it inside the HTML as well.
Save the file and try read-post in the REPL:
Now the router. /blog is an exact match, but /blog/hello-world has to match on the start of the address, so we can pull the slug out of whatever follows /blog/.
case can't express that, so we'll switch to cond, the more general tool. Replace handler with:
There's one small change to make in html-response, right above handler.
Posts can contain accents, curly quotes and other characters that aren't on every keyboard, and the browser has to be told how to read them.
Replace html-response with this version, where the only difference is ; charset=utf-8:
Save the file, then reload and restart in the REPL: (require 'app.core :reload) (app.core/start-server).
Visit /blog and click through from the list. You have a blog!
Then try an address that isn't a post, like http://localhost:8080/blog/nope. You get your 404 page.
Checkpoint: you have a blog that builds its pages from files.
Before you deploy it, there are two things to fix.
Step 7: Break it
The slug in /blog/hello-world comes straight from a URL someone typed, and we're handing it to the filesystem.
What happens if someone asks for a slug that isn't a post at all?
Remember the README.md you created in Part 2? It's in the project root, outside posts/.
Someone could run a command like:
And get your README back as a web page. That's not good.
The slug was ../README, so the program looked for posts/../README.md. That's a perfectly good path, and .. means "go up one folder".
One possible fix is to validate the slug. Add this above read-post:
#"[a-zA-Z0-9\-]+" is another pattern. This one means "one or more letters, numbers, or dashes, and nothing else".
re-matches gives back the text if the whole slug fits the pattern and nil if not, and boolean turns that into true or false.
Save the file and try it in the REPL:
Now make read-post use it. Replace read-post with:
Save the file, then reload and restart in the REPL: (require 'app.core :reload) (app.core/start-server).
Then run the same curl command in the other terminal. Now it gets your 404 page, and your posts still open as before.
Checkpoint: your website now serves posts from files, and it only serves the files you meant it to.
Step 8: Ship the posts
There's one more thing to fix before deploying.
Remember the recipe in Dockerfile.vercel from Part 2? The run stage copies a single file: app.jar.
In Parts 3 and 4 that was enough, because everything new was code inside src, and the code is packed into the jar.
Posts aren't code, so they're not in the jar. Without them, list-posts finds nothing.
So the recipe has to bring the posts folder along. Replace Dockerfile.vercel with:
What changed:
WORKDIR /appin the run stage makes/appthe folder the program runs from.COPY posts postscopies your folder in next to the jar.- The jar is now at
/app/app.jarinstead of/app.jar.
Your project should now look like this:
The whole file
Here is the full src/app/core.clj at this point. If something isn't working, compare yours to this one:
Deploy it
Same command as before:
Open /blog on the live link and click through the posts.
Then write a new one:
Save it as posts/third-post.md, run vercel deploy --prod again, and watch it show up in the list.
Checkpoint: you just published a new blog post without changing a line of code. From now on, that's all it takes: write a
.mdfile and deploy.
If something went wrong
- The blog list is empty: there are no
.mdfiles inposts/, the folder is not in the project root (next todeps.edn), or the REPL was started outsidemy-site. On Vercel, check thatDockerfile.vercelhas theCOPY posts postsline from Step 8. - A post is in the list, but its page is a 404: the file name has a character that
valid-slug?doesn't allow, such as a space, an underscore or a second dot. Rename it using only letters, numbers and dashes. Unable to resolve symbol: escape-html(orpost-title,valid-slug?...): a function is defined below the code that uses it. Move it above.No such namespace: io: if it shows up while you're typing in the REPL, this REPL hasn't seen therequirefrom Step 2. A new REPL starts empty, so run that line again. If it shows up when you reload the file, thensat the top is missing the[clojure.java.io :as io]line.No such var: app.core/list-posts: the REPL hasn't loaded your latest code. Save the file and run(require 'app.core :reload)again.curlstill shows your README after the fix: the running server has the old code. Save the file, then reload and restart in the REPL:(require 'app.core :reload) (app.core/start-server).- A post shows HTML tags like
<b>as plain text instead of formatting them: that'sescape-htmldoing its job. Our posts are plain text with#and##headings, so anything else is shown exactly as typed.
What you learned
- In the REPL we can build a function one piece at a time, quickly learning what works.
mapruns a function on every item of a list andfilterkeeps the items that pass a test. The threading macros->>and->pass a value through a series of steps, so the code reads from top to bottom.- The posts are data: files in the
posts/folder.list-postsfinds them andread-postreads one, so adding a post doesn't need a code change. markdown->htmlturns the few Markdown rules your posts use into HTML, andescape-htmlmakes sure characters like<and&show up as text instead of being read as HTML.condiscase's more flexible sibling: it tries each test in order, which letshandlermatch on the start of a URL.- Anything that comes from outside needs to be checked before we use it.
valid-slug?checks the slug, so/blog/../READMEcan't read files outsideposts/. - A program that reads files needs the files next to it when it runs somewhere else, so the run stage of
Dockerfile.vercelnow copiesposts/too.
Next
That's the end of the series. In five parts you went from an empty folder to a website on the internet, with a home page, an interactive page and a blog, and you wrote all of it yourself.
None of it needed a framework or a database, and only one library besides Clojure itself (http-kit). That was on purpose: when a program is this small, you can see how every piece works.
In Part 1 I said that some of it would be hard, and that you wouldn't understand everything we did along the way. If a part still feels fuzzy, that's normal. Come back to it, change something, break it, and run it again.
I also said that my goal was to help you experience success early, in the hope that it motivates you to keep learning. You have your own website now. If you're wondering what to explore next, here are some suggestions:
- Writing HTML as text is no fun. Hiccup lets you write it as Clojure data instead.
- Matching addresses with
condgets long. Reitit does the matching for you. - markdown-clj handles lists, links, code blocks, and more of what our little converter skips.
To learn more of the language itself, Clojure for the Brave and True is a good place to start, and ClojureDocs is worth keeping open in a tab.
Pick something small that you'd like your website to do, and build it. Good luck!
Bonus: if you get stuck, ask in the Clojurians community on Slack.