Migrating to 1.0

If you've already installed and set up comic_git, you are not required to update to 1.0 if you're happy with your site as is. Not doing so means you won't get access to further bugfixes or enhancements, but if you're okay with that, you don't need to do anything.

If you do want to migrate your site to 1.0, there are three methods to do so:

Make a new repository (recommended for basic users)

This is the quick and dirty way to upgrade, and may be most useful if you haven't made substantial customizations to comic_git or built a readership that goes to the existing URL.

1. Follow the instructions in Creating your own Repository to make a new repo from comic_git 1.0.

2. Copy your your_content and favicon.ico into the new repo.

You're done! This will create a new GitHub Pages URL while keeping your old one intact. You'll need to reset any repository settings or customizations.

Remake your repository (recommended for intermediate users)

This takes a little more effort, but is useful if you want to keep your previous repo name so your readership isn't disrupted by the migration.

1. Back up or move your your_content and favicon.ico files out of the repo directory.

2. On GitHub, go to your repo Settings, then scroll down to the Danger Zone and follow the instructions for deleting your repo.

3. Follow the instructions in Creating your own Repository to make a new repo from comic_git 1.0 using the old name.

4. Move your your_content and favicon.ico back into the new repo.

You're done! This will recreate the GitHub Pages site with minimal effort. However, any customizations such as a custom domain or edited template files in /src will need to be redone.

Surgical update (recommended for advanced users)

This method takes a bit more finesse, but allows you to update your repo to 1.0 without losing any customizations.

1. Move any edited files in /src into /your_content/themes/default .

   1. For example, move any edited templates from /src/templates to /your_content/themes/default .

2. Copy the text in the .github/workflows/main.yaml file from the comic_git repo.

3. Open the .github/workflows/main.yaml file in your own repo and replace all the text in that with the text you copied from comic_git. Save and close the file.

   1. Change the - master line to - working.

   2. You can also choose to just move all your changes into the master branch if you like, in which case leave the line above alone.

4. Delete your /src folder.

5. Add a .nojekyll file to the root of your repo (i.e., alongside favicon.ico).

6. Go to your GitHub Pages settings and change your "Build and deployment" source to "GitHub Actions".

7. Add the line Engine version = 1.0 in the [Comic Settings] section of your comic_info.ini file.

You're done! This is the least destructive method, as it does not delete any repo settings, but does require that you keep track of customized files outside of your_content.

---

Regardless of what option you choose above, you may need to do more work. If you have any customized files (e.g. changes in your src directory, custom templates), you may need to do more updates per the instructions in the next section.

What Has Changed in 1.0?

If you have heavily customized your website (e.g., by making a Theme with custom templates), you will need to be aware of the changes to some of the under-the-hood behavior of comic_git to make sure your changes all work with the new version of the engine.

Template File Changes

This is the list of changes to the names of HTML elements and Jinja variables. Update these in any custom templates you may have.

1. #page-title is now #post-title

2. The following attributes for each page object have changed. These attributes are used by default in the comic and archive templates.

   1. page_title -> _title

   2. post_date -> _post_date

   3. storyline -> _storyline

   4. characters -> _characters

   5. alt_text -> escaped_alt_text

      1. This one is not strictly required, but this way nonstandard characters in your alt text will render properly.

3. Comic pages now support a list of comic images, arranged in alphabetical order. comic_path as a single filepath has been replaced by comic_paths as a list of filepaths. If you plan to only ever have one comic image per page, you can replace any use of comic_path in your templates with comic_path[0]. Otherwise, you should use a for loop to iterate through all the images properly. See the comic.tpl file in comic_git_engine for an example of how to do that.

4. The following IDs have become classes:

   1. comic-image

   2. navigation-bar

5. Anchors to sections on the Archives page now have archive-section- prepended to them. E.g., #archive-section-chapter-3.

6. All references to files in your src directory should now either point to files in comic_git_engine or you should move those files to your Theme directory.

   1. For example, script elements that load the module /src/js/infinite_scroll.js should instead load /comic_git_engine/js/infinite_scroll.js

Comic Info Changes

This is a list of changes to your comic_info.ini file that are required for the 1.0 version of comic_git to work properly.

1. Engine Version is a required value.

2. "Use images in navigation bar" has been moved to Use images in the [Navigation Bar] section.

Code Hooks

Some code hooks will require an update if you have them defined in your hooks.py file.

1. postprocess now takes three arguments:

   comic_info, comic_data_dicts, global_values

Other Changes

This section describes changes that don't fall into any of the other sections describes above.

1. Social Media Preview setup now assumes a default preview_image.png workflow for general pages. If you use a preview image that is not 200px by 200px, set matching og:image:width and og:image:height values in your_content/social_media.json. See Social Media Previews for the current behavior and setup details.

2. Various changes and fixes have been made to the JavaScript and CSS files that were in src, and are now in comic_git_engine. If you have made changes to any of these files, I recommend checking out the current version in comic_git_engine and recreating those files with your changes in your Theme directory.