Lesson 6: The language AI writes in

You have seen it thousands of times on the internet without anybody telling you its name. And over the last few years this simple way of formatting text stopped being just how people write a README.md, and became the native language of AI models.

Markdown

Markdown is not a program. It is an agreement about what a few characters mean, in a file that is still just text.

You write	You get
# Heading	a heading. ## is smaller, ### smaller again, down to ######
- item	a list
**bold** and *italic*	bold and italic
`code`	code, in the middle of a sentence
```python	a whole block of code
[text](https://...)	a link

That is most of it. There is more, and you will pick it up by reading other people’s files. When you want the whole list, CommonMark is the standard and has a ten minute tutorial, and GitHub’s guide covers what most tools added on top of it. Tables are one of those additions, which is why the odd program will not draw them.

The word after the three backticks is the language. Write ```python and anything that renders the file will colour it as Python; ```bash for a terminal, ```text when it is neither. Get it wrong and nothing breaks, you just lose the colours.

You will also see this in note taking tools, and it is worth knowing it is not standard markdown:

[[another note]]

Fact

Every answer you have ever had from an AI was markdown. That is why they arrive with headings, bullet points and bold words: the model writes **like this** and the chat window renders it for you.

It goes the other way too. Paste a markdown file at a model and it reads the structure, not just the words. And a coding agent keeps its own knowledge the same way: its instructions, its skills, the notes it writes to itself, all markdown files sitting in a folder.

Seeing it rendered

Write yourself a file to try this on. Call it notes.md and put a heading, a list and a code block in it.

Two ways to see a markdown file as something other than text:

sudo apt install glow pandoc

glow notes.md                  # read it, nicely, in the terminal
pandoc notes.md -o notes.html  # turn it into a web page

glow is the one for daily use. Open notes.html in your browser to see what pandoc did: that is markdown becoming a web page, and it is a step you will be taking yourself before the end of this course.

The thing worth noticing: the file did not change. notes.md is the same plain text it was, readable by cat, editable in vim, searchable by grep, and it will still open in forty years. The rendering is a convenience laid over the top, not the thing itself.

Going further: a PDF

pandoc turns markdown into HTML. A tool called wkhtmltopdf turns HTML into a PDF. Put the two together and you can hand somebody a proper document.

sudo apt install wkhtmltopdf

Doing it by hand every time would be dull, so it goes in a script. Copy this into md2pdf.sh:

#!/usr/bin/env bash

CSS=css/markdown.css

# Generate PDF from markdown
# $1: markdown filename
# $2: pdf filename
function generate_pdf {
  local temp_html="spec.temp.html"

  pandoc --css $CSS -s -f markdown+smart --metadata pagetitle="Title" --to=html5 $1 -o $temp_html
  wkhtmltopdf --page-size A4 --margin-top 5 --margin-bottom 5 --enable-local-file-access $temp_html $2

  rm $temp_html
}

generate_pdf notes.md notes.pdf

Read it before you run it. You know every piece:

• The shebang from lesson 2, so it can be run by name
• A function, which is a way of giving a name to a few lines. $1 and $2 are whatever you passed it
• local means that variable only exists inside the function
• -s makes pandoc produce a whole HTML page rather than a fragment, and --css points it at a stylesheet
• --enable-local-file-access is wkhtmltopdf being careful. Without it, it refuses to read your CSS file off the disk
• rm cleans up the HTML in the middle, which was only ever scaffolding

chmod +x md2pdf.sh
./md2pdf.sh

Caution

The Ubuntu version of wkhtmltopdf wants a screen to draw on, even though nothing is displayed. If it complains that it cannot connect to a display, put xvfb-run in front of it. xvfb is a screen that does not exist.

sudo apt install xvfb

Task

1. Make a directory for your notes and put it under git. Call it whatever you want
2. Write one note in markdown, about anything from the lessons so far, using everything from today: headings, a list, a link, some code inside a sentence, and a code block with its language named
3. Read it with glow, then turn it into a web page with pandoc and open it in your browser

Commit as you go, not all at once. The note is one commit. The script is another. The stylesheet is a third. Several small commits with honest messages are worth more than one that says stuff, and by the end git log should read like a description of your evening.

Bonus: make it look like yours

The script above points at css/markdown.css, and that file does not exist yet. Write it.

Here is enough to start with. Save it as css/markdown.css and run the script:

body {
  font-family: Georgia, serif;
  max-width: 40em;
  margin: 0 auto;
  line-height: 1.5;
}

h1 {
  border-bottom: 1px solid #ddd;
}

code {
  background: #f4f4f4;
  padding: 0.1em 0.3em;
}

Then change it. Fonts, colours, spacing, margins, whatever you like - it is your document. Commit the CSS as well.

Bonus: take the built files back out

You have been committing everything, which is the right habit to start with. But notes.html and notes.pdf are made from the markdown. Anybody can rebuild them from the file you already committed, so they do not belong in the repository.

Take them out of git without deleting them:

git rm --cached notes.html notes.pdf

--cached is the important word. It removes them from git and leaves them sitting on your disk exactly where they were.

Now stop git offering them again. Make a file called .gitignore, one pattern per line:

*.html
*.pdf

Commit that, then run git status. Quiet.

One honest thing: those files are still in the commits you already made. .gitignore stops git tracking them from now on, it does not reach backwards. Getting something out of history properly is trickier.