Code Hooks

Some parts of comic_git can be customized simply by editing config files or creating new templates. For complex or broader customization options, comic_git provides Code Hooks.

In short, Code Hooks are Python functions that you can write yourself that, if present when comic_git builds your site, will be run in the middle of site building logic. They can affect how that script runs, what values are provided to templates when they build, and more.

To add Code Hooks to your build, create a scripts folder inside your theme directory (if you're not using a theme, put it in the default theme directory). Then, copy the example file from comic_git_engine, /extras/hooks.py, into that folder. You can edit the functions in this file to do anything you want, including calling other Python scripts elsewhere in your repository.

Do Not Change The Working Directory

In comic_git, the working directory is the repository root. Please don't change this, or you risk breaking other things.

List of available hooks

Hook	Description
preprocess	Runs immediately after the main comic's comic_info.ini file is loaded. Can be used to do any setup before the comic starts to build.
extra_page_info_processing	Runs on every info.ini file that's processed, allowing you to do further custom processing to the page info. If you return any non-null value, it will use that in place of the page info that was passed into this hook.
extra_comic_dict_processing	Runs on every comic data dict that's processed, allowing you to do further custom processing to the dict. If you return any non-null value, it will use that in place of the comic data dict that was passed into this hook.
extra_get_storylines_processing	Use this hook to do further processing on the storylines variable, which is used primarily to build the Archive page. This is useful if you wanted to make your archive more complex, like breaking your comic up into Volumes and Chapters instead of just Storylines.
extra_global_values	Returns a dictionary that will be added to the global values sent to all templates when they're built. For example, if you've created a new template which programmatically displays a list of your patrons, you'll need to hook in a new variable. This is where you'd add that variable in.
build_other_pages	This function is called after all other HTML files are built. You can use this function to build whatever additional HTML files you may want, using the utils.write_to_template() function. It's generally recommended that you use the Pages section of your comic_info.ini file to add new pages to your site. However, if you're building pages dynamically, such as separate cast pages for each character, this is where you will do it.
postprocess	Runs at the very end of the comic_git build process. Can be used to do any miscellaneous cleanup you might need.

Additional hooks

Do you have ideas for other code hooks you'd like to see added to comic_git? Please let me know by leaving your suggestion in the comic_git issues page!

Third-Party library support

If you're writing additional code for comic_git, you will likely want to make use of Python's extensive third-party library options. And you can do that! But you will need to do a little more setup.

For any hooks.py script that makes use of additional third-party libraries above and beyond what comic_git already uses, you'll need to create a requirements.txt file in the same folder. The package name for each third-party library you need should be added on a separate line in this file. For example, you can see the packages included in the base requirements file at comic_git_engine's /scripts/requirements.txt:

Jinja2
markdown2
Pillow
pytz

Any requirements you provide in any themes used by your main comic or extra comics will be auto-magically loaded and installed when the GitHub action is run, before the site is built. If you are not using a theme that contains a requirements.txt file, that file will not be loaded and the packages within it will not be installed.

Passing Input Data to Code Hooks

You will sometimes have configuration data that you want to pass to your code hooks that doesn't make sense to include in the code itself. The most common use case is sensitive data that shouldn't be present in code in plain text, like API keys or Discord webhooks. comic_git provides a way to pass this kind of data into your code hook code easily and securely.

The comic_git build_site GitHub Action recognizes two input parameters: INPUTS and SECRETS. INPUTS is for any data that can be stored in plaintext but makes more sense to pass in as an input to your code. SECRETS is for sensitive information that can't be added safely in plaintext, and is the real purpose for this feature. Both these inputs let you provide data to be turned into "environment variables", which are data that can be used easily from anywhere within your code hook.

To use this feature, you will want to update your .github/workflows/main.yaml file so the call-build-site job section at the bottom looks something like this:

jobs:
  call-build-site:
    uses: comic-git/comic_git_engine/.github/workflows/build_site.yaml@v1
    with:
      INPUTS: |
        TZ: PST8PDT
        GOOGLE_SPREADSHEET: abcde12345
    secrets:
      SECRETS: |
        PATREON_API_KEY: ${{ secrets.PATREON_API_KEY }}
        AIRTABLE_API_KEY: ${{ secrets.AIRTABLE_API_KEY }}

When the build_site.py Python script runs, this will cause four new environment variables to be created: TZ, GOOGLE_SPREADSHEET, PATREON_API_KEY, and AIRTABLE_API_KEY. TZ and GOOGLE_SPREADSHEET will both have the values shown after the : in the YAML file. PATREON_API_KEY and AIRTABLE_API_KEY will have the values defined in the GitHub Secrets of the same name that you have defined in your repository. (See the next section for how to do that.)

Each variable must be on its own line, and the "key" (e.g. GOOGLE_SPREADSHEET) must be separated from the "value" (e.g., abcde12345) by a colon (:). Any leading or trailing whitespace will be stripped from both the key and the value when they're parsed into environment variables.

To reference these environment variables in your code, you just need to use the os.getenv() function, like so:

api_key = os.getenv("PATREON_API_KEY")
... (use the API key for something)

Do NOT put sensitive data in plain text! Use Secrets!

If you have any data that gives you access to a service or personal space, like an API key or a Discord webhook, it is HIGHLY RECOMMENDED that you use secrets to save this data. While it may be less convenient to use than saving that data in plain text, it is MUCH more secure and will protect you against people that want to steal your information, impersonate you, blackmail you for access to your data, or worse.

Adding GitHub Secrets

To add data to GitHub Secrets so that it can be used by comic_git, go to Settings in your repository.

In the sidebar, click Secrets and Variables, and then click Actions.

In the new window that opens up, you'll see a list of all Secrets that have been created for your repository. This list starts out empty. To add a secret, click the green New Repository Secret button.

This will take you to a new page where you will add your secret. Give it a name (the standard practice is to give it a name IN_THIS_FORMAT), then put the actual secret value in the "Secret" section. If you're saving an API key, this is where that key goes.

When you're done, click the "Add secret" button, and the secret will be added to your list of Repository Secrets, and will be available to your repository to pass on to the build_site GitHub Action via the SECRETS input as described above.

You can now add more secrets if you want. From this page, you can also edit or delete existing secrets. Note that you can not view secrets that you've saved here. If you need those secrets for anything else, make sure to save a copy separately.

This page also lets you set up Environment Secrets or Variables that can be used in a similar way. How do use those is beyond the scope of this document.

Adding Collaborators to your Repository

When you create your own comic_git site for the first time, you will be the only one who can edit it at first. And if you make a private repository, you'll be the only one who will even be able to see it. If you want someone else to help you with your site, or even just to look at your GitHub Actions to help figure out why your build might have broken, you will likely need to add them as a "collaborator".

To do this, go to your Settings tab in your repository

Then click on Collaborators in the sidebar

GitHub may ask you to sign back in. After that's done, you'll be taken to the Collaborators page. To add a collaborator, click the Add People button.

A dialog will pop up that will let you search for a user by username, full name, or email.

Use any of those to find the person you want to add, and they'll show up in the list of possible users.

Click the name of the person you want to invite as a collaborator, then click the green "Add <name>" button.

WARNING: The list of people that show up in this dropdown are pulled from the list of ALL GitHub users. Adding someone as collaborator gives them the ability to make changes to your website! Make sure the person you select is who you actually think they are!

If you accidentally add the wrong person as a collaborator, don't worry, it's easy to remove them later.

After clicking the "Add" button, the person you selected will show up in the list of collaborators with "Pending invite" next to their name.

This means GitHub has sent them an email inviting them to be a collaborator on your repo. The email will look like below:

That user will now need to click the "View Invitation" button, which will take them to the GitHub website, which will prompt them Accept or Decline the invitation.

Once they click "Accept Invitation", they'll show up as a collaborator in your Collaborators list.

Collaborators have full access to change and modify any code in your repository! And they'll be able to view your repository if it's set to Private. However, collaborators can not view or change any Settings on your repository, so you're not at risk of them deleting your repo or locking you out.

Removing Collaborators

To remove a collaborator, simply go to the list of collaborators on your repository and click the red trashcan beside the collaborator's name.

GitHub will pop up a dialog asking you to confirm you want to remove this collaborator. Click the "Remove" button, and the collaborator will be removed.