Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Building Your Website On Your Own PC

Building your Website on your own PC

While it's very convenient that GitHub can build and deploy your website itself with no further required input from you, trying to make changes to the design or layout of your website can be a slow process. You have to make a change, then commit the change, then push, then wait for GitHub Pages to rebuild... then do that over and over until your website looks how you want. It can be VERY tedious and unpleasant.

Fortunately, it's possible to build your website locally without pushing to GitHub! This is very useful for testing changes to your website quickly and efficiently. This section will walk you through that.

Install Python

The main brain of the comic_git workflow is a Python script that is run whenever you push a change to GitHub, so to build your website locally, you will need to run that script.

First, download the most recent version of Python from the Python website.

comic_git requires Python 3.12 or greater.

Install Python on your computer, and follow the instructions. If there are options to add Python to your PATH, enable it.

Next, verify that Python is installed and working on your machine.

Windows

Open the Command Prompt. Type in the following command, and you should get back the version of Python currently installed on your PC.

C:\Users\JohnSmith> python --version
Python 3.13.4

If you're on Windows 7 or lower and the install didn't work properly, you'll see something like below. If you are on Windows 10, Windows may automatically open up the Windows Store to download Python. If it does, close it and move on.

C:\Users\JohnSmith> python --version
'python' is not recognized as an internal or external command,
operable program or batch file.

In this case, check that Python was installed by finding the python.exe file, which will usually be found at C:\Users\<username>\AppData\Local\Programs\Python\Python38\python.exe. If you cannot find this file, try reinstalling Python.

Otherwise, Python was not added to your PATH properly. You can do so yourself by following these instructions. You may need to restart your PC afterwards.

Mac

Python has full documentation on installing Python on Mac.

Linux

Python has full documentation on installing Python on different flavors of Linux.

Add comic_git_engine to your repo

To work on GitHub, comic_git is split into two repositories: your personal content repo and comic_git_engine, which hosts all the necessary scripts to build the site. When running locally, you won't be able to access the engine repo. These instructions will install the engine into your local repository so you can make use of it.

In a terminal window, navigate to your base repo directory. This is the directory which contains your_content, .github, and so on. We'll assume it's D:\GitHub\comic_git for these instructions.

Type the following command:

In that command line, replace [engine version] with the same value as the Engine version listed in comic_info.ini.

This installs comic_git_engine as a submodule of your personal repo.

When building your site locally, you'll use the local version of comic_git_engine, which may not update when the live repo updates. You can manually update it to the newest version with the command git submodule update --remote.

If you ever want to use a different version of the engine, you can switch it by going into your comic_git_engine directory and running git checkout <version>, where <version> is a branch or release tag such as latest.

Install the required libraries

Your next step is to install the libraries needed for comic_git to build your website. Fortunately, Python comes with a tool that can automatically do this for you called pip.

Open up your Command Prompt/Terminal in your base repo directory and type the following command:

pip will then install a number of Python packages on your computer. Once it's done, you'll see something like below:

If you are using Code Hooks and any active theme for your main comic or Extra Comics includes a scripts/requirements.txt file for extra Python libraries, install the libraries from each of those files directly as well.

If you use different themes for your main comic and any Extra Comics, repeat this for each theme that has its own scripts/requirements.txt file.

Provide your website address locally

There is some necessary information GitHub provides to comic_git that is not available automatically on your local machine. The cleanest option is to set GITHUB_REPOSITORY in the terminal before building:

You can instead provide the domain and subdirectory in comic_info.ini:

Edit your comic_info.ini file to add two new options at the bottom of the [Comic Settings] section.

username should be your GitHub username, and repo_name should be the name of the GitHub repo you created. However, if you set up your GitHub Pages to serve from a custom domain, replace everything in Comic domain with that and leave Comic subdirectory blank.

For comic_info.toml, the equivalent values are site.comic_domain and site.comic_subdirectory. See TOML Configuration.

Run the build_site.py script

Once your local setup is ready, you can build your site directly on your own PC. Before you do, make sure your repo contains a your_content/site_root/ folder. comic_git expects that folder to exist even if it is empty.

comic_git will then build your website using your current templates, settings, and comic files. By default, the finished site is written into a build folder inside your repo.

When the script finishes, look in build for the generated site files. In most local workflows, this is the folder you will:

  • preview in a browser

  • inspect while testing template changes

  • upload if you are hosting somewhere other than GitHub Pages

Using a different output folder

If you want comic_git to build somewhere other than build, use the --output-dir argument.

For example, if you want the generated site to go into a folder called preview_site:

This is especially useful when you want the output folder name to match your Comic subdirectory for local browser testing.

If you specifically want comic_git to write the generated HTML files directly into the repo root instead of a separate folder, you can still set OUTPUT_DIR to an empty value before you run the build script. That older environment-variable approach is mainly useful for advanced cases.

You should run the build script again any time you change:

  • comic_info.ini

  • comic_info.toml

  • any page info.ini file

  • any page info.toml file

  • any .tpl template

  • any Python script used by your build

  • your comic page folders or page files

If you want to convert existing INI and page text files to TOML, use the dry-run-first process in TOML Configuration.

If you only change CSS or JavaScript files, you usually do not need to rebuild. In most cases, refreshing your browser is enough.

Auto-rebuilding preview server

For theme and content work, comic_git includes a preview server that rebuilds when supported source files change. Install its optional watcher once:

Then run this from your comic_git repository root:

The command prints the local URL to open and watches changes to TOML, INI, text, Markdown, HTML, and template files. Press Ctrl+C to stop it.

To include future-dated pages in a local preview without deleting their source folders, use:

Do not use --delete-scheduled-posts for an ordinary local preview.

Generated HTML files are temporary build output

With the default build workflow, editing generated HTML files is less risky than it used to be because those files live in their own folder. But they are still temporary build output, and your changes will be overwritten the next time you rebuild.

If you want to change how a page is generated, edit your existing Theme instead.

Deleting auto-generated files

With the default setup, all of your generated local site files live in build. If you want to clear them out, you can simply delete that folder and rebuild it later.

If you are using a custom output folder, delete that folder instead.

If you are using the old in-place build behavior described above, the helper script below is useful because it removes the generated HTML files from your repo root for you.

Viewing your Website on your own PC

You've learned how to build your website on your local PC. However, you also need to be able to view your website. While you can open the individual HTML files, this doesn't replicate a full server environment.

By default, comic_git builds your generated site into the build folder. That means:

  • If you just want to inspect the generated files or upload them somewhere else, use the contents of build.

  • If you want to run a simple local web server, the exact instructions depend on whether your Comic subdirectory is blank.

If Comic subdirectory is blank

If your site is hosted directly at the root of your domain, and Comic subdirectory is blank in comic_info.ini, you can preview the default build folder directly.

Navigate to your repo directory and run:

Then open http://localhost:8000 or http://127.0.0.1:8000 in your browser.

If Comic subdirectory is set

If your site uses a non-empty Comic subdirectory (the usual GitHub Pages setup), the generated links expect your site to live at a URL like https://username.github.io/repo_name/. Because of that, serving the build folder directly from http://localhost:8000/ will not match the URLs comic_git generated.

For a local browser preview in this case, set --output-dir to the same value as Comic subdirectory, then rebuild your site. For example, if Comic subdirectory = comic_git, run:

This will create a folder in your repo with the same name as your configured subdirectory, which makes the local URL structure match what comic_git generated.

Then start the web server from your repo root:

Once this appears, open your web browser and go to either http://localhost:8000/comic_git or http://127.0.0.1:8000/comic_git (Replace comic_git in the URL with the name of the folder your repository is in). You should see your site pop up exactly as if it's been published to the web!

To stop the web server, go into the command prompt window where you ran the command above and hit Ctrl+C.

Why the URL needs to include your repo's folder name

Putting comic_git at the end of the URL above is necessary because the web server will use the directory that you launch it from as the URL root. Meaning, it will serve all the folders and files it finds in that directory when you go to http://localhost:8000. To have it display your website correctly, the generated site files need to be inside a folder whose name matches your Comic subdirectory setting.

The default setup for GitHub Pages is to serve your website from https://<username>.github.io/<repo_name>, rather than from https://<username>.github.io/ . Because of that, comic_git builds all its links in your website (including the ones to CSS and JavaScript files necessary to run the site) by prepending whatever value you put in your "Comic subdirectory" config option above to all links. If it didn't, then your website wouldn't load any CSS properly, and all links to pages within the site would be broken!

If you're hosting directly from the root of your domain (e.g., https://www.tamberlanecomic.com), and your "Comic subdirectory" config option is blank, then you do not need this in-place preview workflow at all. You can simply serve the default build folder directly as described above.

PreviousChanging Your Website URL
NextHosting comic_git Elsewhere

Last updated