Migrating to 1.1

If your comic_git site is already working, and you are happy with it, you do not have to move to 1.1 right away.

However, if you want the new features and fixes in 1.1, this upgrade should be much simpler than the move to 1.0.

For most users, upgrading to 1.1 is mainly:

1. update your Engine version to 1.1

2. update your GitHub Actions workflow to use the v1.1 build action

3. move website files such as favicon.ico and .nojekyll from the repository root into your_content/site_root

4. rebuild or republish your site, then check any customizations

Basic upgrade steps

If you are already using the 1.0 engine layout, start here:

1. Open your comic_info.ini file.

2. In the [Comic Settings] section, update:

Engine version = 1.1

1. Open your .github/workflows/main.yaml file.

2. Find the call-build-site job and update the uses: line to point to the v1.1 version of the reusable workflow:

uses: comic-git/comic_git_engine/.github/workflows/build_site.yaml@v1.1

1. Move files that need to go at the root-level of your website into the your_content/site_root/ folder. Create that folder if necessary.

Move only the files that need to appear at the root of the published website into it. Even an uncustomized older comic_git repository normally has favicon.ico and .nojekyll in the repository root, so move those files to your_content/site_root/favicon.ico and your_content/site_root/.nojekyll. You may have other files that need to be moved as well, like CNAME if you use a custom domain.

Do not move every file or folder from the repository root. Leave repository and build files such as .gitignore, .gitattributes, .gitmodules, README.md, LICENSE, .github/, comic_git_engine/, and your_content/ where they are. If you can see a .git/ folder, leave that in place too. These items help GitHub and comic_git manage and build your site; they are not files for the published website.

1. Rebuild or republish your site normally.

2. Check your site for any custom workflows, themes, or expert-level setup that may need to be updated.

If you do not use any advanced customizations, that may be all you need to do.

The workflow version and engine version are separate choices. The values above follow compatible 1.1 patch updates. For an exact, reproducible 1.1.0 build, use workflow tag v1.1.0 together with engine version 1.1.0.

---

What changed in 1.1?

Version 1.1 adds several end-user features, including:

• optional TOML Configuration for comic settings and page content

• structured per-image titles, alt text, and thumbnails on multi-image pages

• page-based or image-based Archive entries, including text-only page support

• customizable Social Media Previews

• built-in support for deploying to Neocities

• a documented Webring feature

• more RSS feed options for Extra Comics

Most of these are new features, not breaking changes.

Your existing INI and text files remain supported. Moving to TOML is optional and can be done later.

The main migration concerns in 1.1 are for people who use advanced or custom setup.

Changes advanced users should check

Local build script paths changed

If you run engine scripts directly on your own computer, some important file paths have changed.

Update any custom notes, scripts, shortcuts, or external tooling that still points to the old paths.

Also note that local builds now write the finished site into build by default unless you explicitly override OUTPUT_DIR. Check your .gitignore file and add build/ if the folder is not already ignored.

Common path updates:

• comic_git_engine\scripts\build_site.py is now comic_git_engine\src\build\build_site.py

• comic_git_engine\scripts\delete_autogenerated_files.py is now comic_git_engine\src\scripts\delete_autogenerated_files.py

• comic_git_engine\scripts\requirements.txt is now comic_git_engine\requirements.txt

Custom Python code may also import old engine modules rather than run them directly. Search your theme scripts and other custom Python for imports beginning with comic_git_engine.scripts; those paths no longer exist. For example, helpers formerly imported from comic_git_engine.scripts.utils now live in core.utils when your code runs as part of the comic_git build:

from core import utils
from core.utils import checkpoint, find_project_root, print_processing_times, read_info

The documented Code Hook names, arguments, and page objects are the supported extension API. Other engine modules and helpers may move between releases, so custom code that imports them should be reviewed during upgrades. A standalone Python script does not automatically have comic_git_engine/src on its import path; either run that code through a Code Hook or explicitly add that folder to the standalone script's Python path.

If you build locally and use Code Hooks with extra Python libraries, your local setup should also match the current GitHub Actions workflow:

python -m pip install -r comic_git_engine\requirements.txt
python -m pip install -r your_content\themes\<theme>\scripts\requirements.txt
python comic_git_engine\src\build\build_site.py

See Building Your Website On Your Own PC for the current local workflow.

Neocities workflow settings may need updating

If you already set up a custom Neocities deployment workflow before the current docs existed, review it carefully.

In particular:

• update the uses: line to comic-git/comic_git_engine/.github/workflows/build_site.yaml@v1.1

• use OUTPUT_DIR: build for Neocities deploys

• use NEOCITIES_CLEAN, not NEOCITIES_CLEAR

• make sure your Neocities API token is stored as NEOCITIES_API_TOKEN

See Hosting comic_git Elsewhere for the current setup.

Webring behavior may need updating

If you experimented with the webring feature before it was fully documented, check your setup against the current rules.

In particular:

• Webring ID is now required whenever the webring feature is enabled

• local testing should use Endpoint = local

• settings like Exclude own comic from members depend on Webring ID matching your member id exactly

See Webring for the current setup.

Social Media Preview setup should be reviewed

If you already customized Social Media Preview behavior using older examples or partial docs, review your setup against the current feature docs.

In particular:

• image size metadata should be set through og:image:width and og:image:height in your_content/social_media.json

• you can override preview images by replacing your_content/images/preview_image.png or by setting og:image directly

• Extra Comics now fall back to the main comic's your_content/social_media.json if they do not define their own file

See Social Media Previews for the current setup.

Custom templates and Code Hooks must use structured page data

Version 1.1 represents every comic page as a structured page object with an ordered list of image objects. Default themes already support this, but custom templates or hooks that depend on 1.0 dictionaries may need changes.

Copied templates are complete replacements and do not automatically receive fixes made to the engine's templates. Compare each template your theme overrides with the current engine template, especially comic.tpl, archive.tpl, tagged.tpl, and infinite_scroll.tpl.

Common replacements include:

Older template value	1.1 replacement
comic_paths	ordered images, using image.web_path for each image
escaped_alt_text	image.alt_text, normally rendered with | e
page-wide thumbnail_path	page.thumbnail_path, or entry.thumbnail_path in an Archive loop
_title	page.title, or entry.title in an Archive loop
archive_post_date or _post_date in an Archive loop	entry.post_date
a hand-built Archive URL using page_name	entry.page_url plus the content fragment shown below

Preserve the image list's order and add the positional anchor when a custom comic template renders images:

{% for image in images %}
<div class="comic-image-container" id="comic-image-{{ loop.index }}">
    <img src="{{ base_dir }}/{{ image.web_path | e }}" alt="{{ image.alt_text | e }}">
</div>
{% endfor %}

Custom Archive templates must also link each entry to the content it represents. This is what makes separately listed images open at the correct image instead of the top of the same page:

<a href="{{ entry.page_url | e }}#{{ "comic-image-" ~ entry.image_index if entry.image_index else "post-body" }}">

An Archive entry may have no thumbnail, particularly for a text-only post, so custom templates should check entry.thumbnail_path before rendering an <img>. Use {{ base_dir }}/{{ entry.thumbnail_path | e }} rather than assuming the site is published at the domain root.

Custom Infinite Scroll chapter navigation should use infinite_scroll_chapters, not the first item in each storylines group. Archive settings can change what storylines contains.

Page-related Code Hooks now receive objects rather than dictionaries. Read standard data through attributes, and put custom page values in page.extra:

page_name = page.page_name
page.extra["transcript_json"] = languages

Public values in page.extra appear in the page's extra object in page_info_list.json; keys beginning with ! remain private. A hook that previously copied a page dictionary and added template values must instead build its custom template context explicitly from the page attributes, configuration, and its own values. In particular, build_other_pages receives comic_folder, comic_info, and list[ComicPage], not a ready-made template dictionary or the final global_values dictionary.

See Template and Hook Data and Code Hooks.

Custom page metadata consumers must use the new format

The public comic/page_info_list.json file now contains a versioned document with structured pages and images. If you have custom JavaScript or another tool that reads this file, update it to use schema_version and the pages list. See Generated Page Metadata for the current format.

Archive behavior has new options

The Archive defaults to one entry per page. You can opt into one entry per image with List images separately = True. When images are listed separately, Show text-only posts controls whether pages without images remain listed, and Image title fallback controls titles for images without their own title.

Existing sites retain page-based behavior unless they enable the new mode. See the Archive settings.

TOML migration is optional

comic_git can read comic_info.toml and page info.toml files, and includes a dry-run-first migration command. A TOML file takes complete precedence over its matching legacy file rather than merging values.

Do not delete your legacy files until you have reviewed the TOML and successfully rebuilt your site. See TOML Configuration for the command and safety steps.

Check your site layout on mobile

Version 1.1 includes a number of CSS changes to improve mobile responsiveness.

Those changes should be helpful for most sites, but if you have custom CSS, a custom Theme, or edited templates, it is a good idea to check that your layout still looks the way you expect on smaller screens.

In particular, check:

• your homepage

• comic pages

• navigation bars

• archive pages

• any heavily customized themed pages

What probably does not need migration work

Many 1.1 changes are improvements or new options that do not require you to change existing files unless you want to use them.

For example:

• the new Neocities docs do not affect GitHub Pages users

• the Webring feature does not affect you unless you enable it

• the new RSS feed options for Extra Comics are optional

• the mobile style improvements and banner sizing fixes do not require manual action

Recommended upgrade check

After moving to 1.1, it is a good idea to check:

1. your site still builds successfully

2. your .github/workflows/main.yaml file points to comic-git/comic_git_engine/.github/workflows/build_site.yaml@v1.1

3. local build instructions, imports, or helper scripts you use still point at the right engine files

4. any Neocities workflow you use still matches the current parameters

5. any Webring setup you use still matches the current documented behavior

6. any Social Media Preview customization still matches the current docs

7. custom templates and Code Hooks use the 1.1 page and image objects and preserve positional links

8. any optional TOML migration builds correctly before legacy files are removed

If all of those look correct, your upgrade is probably complete.