A guide to starting with Publ
This guide will walk you through setting up Publ on your local computer so that you can build and run a site that runs locally. To learn how to run this website on a webserver, see the deployment guides.
You’ll need Python (at least version 3.6), and it’s a good
idea to use a virtual environment manager as well. Any such manager
poetry) is fine; the following instructions all
On macOS this is pretty straightforward; after installing Homebrew you can install Python with:
Your distribution probably provides packages for python3; make sure to get
python 3.6 or later, and to also install
When you install, make sure to check the option for “add python to your PATH” and if you customize the installation, make sure it installs pip as well
Install Visual Studio, making sure to select “Visual C++ build tools” at the very least.
This is unfortunately necessary for some of the libraries Publ depends on. You can either install the Visual Studio Community Edition, or you can install just the build tools (under the “Tools for Visual Studio” section).
(Optional, but recommended) Install some sort of
bashenvironment, such as MinGW.
The “git bash” that comes with Git for Windows is a pretty good choice.
Clone a local copy of this website repository.
You can use the command line (e.g.
git clone https://github.com/PlaidWeb/Publ-site) or you can use your favorite git frontend for this (such as GitHub Desktop).
Launch the website locally
On macOS and Linux, or on Windows using git bash, run
./run.sh(also from the same directory).
On Windows, double-click the
winrun.cmdfile (which may appear as just
After the site reindex completes, connecting to
http://localhost:5000 should show you this website.
If you need to run the site on a different port (for example, you get an error
OSError: [Errno 48] Address already in use), you can change this by
FLASK_RUN_PORT environment variable; for example:
will run the site at
To make your own Publ-based site, you’ll want to create a new virtual
environment to hold Publ in. As above, the following instructions assume
poetry, although any other manager is fine.
Next, you’ll need an
app.py file. Here is a pretty minimal one:
Now, you’ll need directories for your site content; create folders named
static in the same directory as
app.py. From the
command line you can type:
Then you can launch your (not yet very functional) site with
Now you should have a site running at
http://localhost:5000 that does absolutely nothing!
Also, feel free to copy the
winrun.cmd from this
website which will better automate subsequent setup steps.
For a fairly minimal site, create the file
Now you can finally create a content file; for example, create a file called
first-entry.md in the
After Publ sees the content file, it should now get some extra stuff in the
headers, namely a
Entry-ID, and a
UUID. These are how Publ tracks
the publishing information for the entry itself. It’s a good idea to leave them
alone unless you know what you’re doing.
Anyway, read on for more information about how to build a bigger site!
Looking at the files for this site, here are some key things to look at:
poetry.lock: Package dependencies
app.py: Main “application” that runs the site
Procfile: Configures the site to run on Heroku
templates/: The site layout files (i.e. how to lay your content out). Some you can look at:
content/: The content on this site (for example, this page’s content is stored in
style.css: the global stylesheet
lightbox: A library used for presenting images in a gallery (example page)
pygments.default.css: A stylesheet used by the Markdown engine when formatting code
For more information about templates, see the manual on template
formats. The only absolutely required template is
index.html, but it’s a good idea to also provide an
For more information about content, see that manual page.
I also have made some of my own website templates available.
Getting a Publ site online depends a lot on how you’re going to be hosting it. If you’re savvy with Flask apps you probably know what to do; otherwise, check out the deployment guides to see if there’s anything that covers your usage.