Building caseorganic.com
How to run build.py on a Mac, preview the site, publish drafts, redirect old addresses, and use the sitemap.
Running the build
You run build.py from Terminal. The project includes a venv folder with the Python libraries the script needs, so you switch that on first.
- Open Terminal. Press Command + Space, type "Terminal," and press Return.
-
Go to the project folder. Type
cdfollowed by a space, then drag the caseorganic-site folder from Finder into the Terminal window. Terminal fills in the folder's location. Press Return. -
Switch on the project's Python environment. The start of the line changes to show
(venv).source venv/bin/activate -
Build the site and start a preview.
python build.py --serve - Look at the site. Open http://localhost:8000 in your browser. The sitemap is at http://localhost:8000/sitemap.xml.
- Stop the preview. Press Control + C in Terminal.
Each new Terminal window starts fresh, so repeat steps 2 and 3 every time you open one.
Other commands
| Command | What it does |
|---|---|
python build.py | Builds the site into the dist folder without starting a preview. |
python build.py --serve | Builds the site and previews it at localhost:8000. |
python build.py --serve 8080 | Same as above on a different port, useful if 8000 is already in use. |
python build.py --new "Title" | Creates a new post folder in this year's content folder with a starter index.md. Add --type talk (or essay, podcast, book) to set the type. |
Publishing the site
Every build writes the finished website into the dist folder, replacing what was there before. Upload the contents of dist to your web host. Never edit files inside dist directly, because the next build erases them. Make changes in content, static, or config.yaml instead.
Drafts
A post whose frontmatter includes draft: true is skipped during the build. It does not appear on the site, in the sitemap, or in search, and its redirects are not created. To publish it, paste in the article text, delete the draft: true line, and build again.
Redirecting old addresses
Older versions of the site used different address patterns, such as /2015/03/post-name, /posts/post-name, and /post-name. The current site publishes every article at /post/post-name/. To keep links from other websites working, list a post's old addresses in its frontmatter:
aliases:
- /2015/03/from-esri-to-calm-tech-my-next-steps
- /posts/from-esri-to-calm-tech-my-next-stepsOn each build, the script creates a redirect page at every listed address and adds a permanent (301) redirect for each one to dist/_redirects, a file that Netlify and Cloudflare Pages read automatically. If an alias matches a real page, the build prints a warning and skips it.
To check a redirect, run the preview and visit the old address, for example localhost:8000/2015/03/from-esri-to-calm-tech-my-next-steps. It should open the current article.
Sitemap and robots.txt
Each build writes dist/sitemap.xml, which lists every published page for search engines. Redirect pages and drafts are left out. Article entries use the post's date: line, or its updated: line if you add one after revising a post.
The build also writes dist/robots.txt pointing to the sitemap. If you keep your own robots.txt in the static folder, the build leaves your rules in place and adds the sitemap line at the end.
The sitemap uses https://caseorganic.com as the site address. If the site runs on the www version, add this line to config.yaml:
site_url: https://www.caseorganic.comAfter uploading, submit https://caseorganic.com/sitemap.xml in Google Search Console under Sitemaps so Google recrawls the site.
Troubleshooting
"No module named yaml" or "No module named markdown"
The environment is missing a library. With (venv) showing, run this once, then build again:
pip install -r requirements.txt"command not found: python"
The environment is not switched on. Repeat steps 2 and 3 above. If it still fails, use python3 in place of python.
"Address already in use"
A previous preview is still running, possibly in another Terminal window. Press Control + C in that window, or start the preview on another port with python build.py --serve 8080.
A post is missing from the site
Check its index.md for a draft: true line, and check that the file sits inside a year folder such as content/2015/post-name/index.md. The build lists every file it loads in Terminal, so you can confirm whether it was picked up.