> For the complete documentation index, see [llms.txt](https://comic-git.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://comic-git.gitbook.io/documentation/additional-information/migrating-to-1.1.md).

# 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:

```ini
Engine version = 1.1
```

3. Open your `.github/workflows/main.yaml` file.
4. Find the `call-build-site` job and update the `uses:` line to point to the `v1.1` version of the reusable workflow:

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

5. 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.

{% hint style="warning" %}
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.
{% endhint %}

6. Rebuild or republish your site normally.
7. 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](/documentation/advanced-editing/toml-configuration.md) 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](/documentation/advanced-editing/social-media-previews.md)
* built-in support for deploying to [Neocities](/documentation/expert-editing/hosting-comic_git-elsewhere.md#uploading-to-neocities)
* a documented [Webring](/documentation/expert-editing/webring.md) feature
* more RSS feed options for [Extra Comics](/documentation/advanced-editing/adding-an-rss-feed.md)

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:

```python
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](/documentation/expert-editing/code-hooks.md) 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](/documentation/expert-editing/building-your-website-on-your-own-pc.md) 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](/documentation/expert-editing/hosting-comic_git-elsewhere.md#uploading-to-neocities) 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](/documentation/expert-editing/webring.md) 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](/documentation/advanced-editing/social-media-previews.md) 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](https://github.com/comic-git/comic_git_engine/tree/latest/templates), 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:

```jinja2
{% 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:

```jinja2
<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`:

```python
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](/documentation/expert-editing/template-and-hook-data.md) and [Code Hooks](/documentation/expert-editing/code-hooks.md).

### 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](/documentation/expert-editing/generated-page-metadata.md) 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](/documentation/basic-editing/editing-your-comic-info.md#archive).

### 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](/documentation/advanced-editing/toml-configuration.md#migrating-existing-files) 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.