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.
On macOS this is pretty straightforward; after installing Homebrew you can install these things with:
and then add the following line to your login script (usually
Your distribution probably provides packages for python3; make sure to get
python 3.5 or later, and to also install
keeps this in the
python3-pip package; other distributions will vary).
Afterwards, you can install
pipenv with either:
If you do the latter, make sure your pip user directory is on your
will probably be
$HOME/.local/bin but it might vary based on your
pip3 doesn’t work, try running just
pip instead; not all
distributions differentiate between Python 2 and 3 anymore.
If your distribution doesn’t provide an easy recent version, consider using pyenv.
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.
From a command prompt (e.g. git bash, a Windows CMD prompt, or from “Run program…” from the start menu):
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).
Run the Publ setup script
On macOS and Linux, or on Windows using git bash, open a command prompt and
cdinto where you checked out the files, and run
On Windows, double-click the
winsetup.cmdfile (which may appear as just
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
Now, connecting to
http://localhost:5000 should show you this website. Note that on the first page load it will take a little while before all of the content is visible – but you can watch the site build in your terminal window to see it finish.
If you need to run the site on a different port (for example, you get an error like
OSError: [Errno 48] Address already in use), you can change this by setting the
FLASK_RUN_PORT environment variable; for example:
will run the site at
To make your own Publ-based site, you’ll need to use
pipenv to set up a sandbox and install the
Publ package to it. I recommend
pipenv for a number of reasons but if you’re familiar with
virtualenv or are
using a hosting provider that requires it, feel free to do that instead.
You can copy the
run.sh from the main site, and also
winrun.cmd if you would like to run it on Windows.
If you’re using
pipenv the command would be:
and if you’re doing the
virtualenv approach it would be:
Next, you’ll need a
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
if you’re using
if you’re using
virtualenv. (Both must be run from the same directory as
Now you should have a site running at
http://localhost:5000 that does absolutely nothing! Congratulations!
The following template files are available from the publ site repository.
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:
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 required templates are
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.