Next steps

Tasks to do in your template project after applying the template to it.

While most of the steps to take after using the template are listed in the created TODO.md file within the newly created template project directory, this document details some of these steps a bit more. Use this guide alongside the TODO.md to complete those tasks.

One of the first set of tasks to do (as listed in the TODO.md file) is to get Git to track the template with git init and adding these files to the Git history. Usually it’s better to first search for and complete all the TODO items throughout the project and only then add the files to the Git history, it’s also fine to add and commit everything just to get the repository set up. So, at the minimum, the next commands to do while in the template project’s working directory is to:

bash {.filename="Terminal"} git init -b main git add . # `chore` is a Conventional Commit tag. git commit -m "chore: start of project"

After that, there are two sets of tasks described in this document: required and optional.

Required

These next steps are required in order to actually set up the new template’s website.

Setting up a GitHub repository

One of the main purposes of this template is to set up a new template that can be easily used by others for whatever project that template will be used for (e.g. websites, Python packages). Which means the template project’s Git repository needs to be hosted somewhere, like GitHub.

The quickest and easiest way of putting your template project on GitHub is to use the gh command line tool to upload the Git repository to GitHub:

Terminal

gh repo create --source=. --public --push USER/REPO

Note

If you’re using the template to create a template project within the Seedcase Project’s GitHub organization, use the instructions below that use a custom command line tool. We built this tool to help us manage our many GitHub repositories across several projects. While it’s useful for us, it isn’t designed or built in a way that makes it easy for others to use (yet).

For setting up a GitHub repository for the created template project that will be part of the Seedcase Project, you’ll need to install our internal tool spaid and use the following commands to run the next setup steps:

Terminal

spaid_gh_create_repo_from_local -h
spaid_gh_set_repo_settings -h
spaid_gh_ruleset_basic_protect_main -h
spaid_gh_ruleset_require_pr -h

Some configuration may need to be done after copying this template to a new repository if the configurations haven’t been set at the organizational level, including configurations external to the repository. Some GitHub workflows require installing GitHub Apps, for greater security purposes and easier administration when managing multiple repositories. The security section in our Guidebook provides some instructions on how to set up GitHub Apps, secrets, and variables. Ideally the secrets and variables should be set up in the organization settings. The specific workflows in this template that require this additional setup are:

• The workflow .github/workflows/release.yml requires the auto-release-token GitHub App, which is specific to the Seedcase Project, as well as a creating a GitHub secret called UPDATE_VERSION_TOKEN and a variable called UPDATE_VERSION_APP_ID that has the App ID.
• The workflow .github/workflows/add-to-project.yml requires the add-to-board-token GitHub App (another Seedcase app), along with the ADD_TO_BOARD_TOKEN secret and the ADD_TO_BOARD_APP_ID variable of the GitHub App’s ID.

Adding the Quarto theme

Warning

This step is only necessary if you are using this template for a repository that is part of the Seedcase Project. If you are using this template for a different project, you can skip this step. If you have your own Quarto theme that you want to use, you can use this step as a general guide on how to add a Quarto theme to your project.

For Seedcase Project repositories, we have a custom Quarto extension that has our theme called seedcase-theme. The justfile has a recipe called update-quarto-theme that adds this theme to the project. Run it by opening a terminal within the project directory and running the following command:

Terminal

just update-quarto-theme

This adds the seedcase-theme Quarto theme to the website, which provides a consistent look and feel across all Seedcase Project websites. It’s called update-quarto-theme here since you can use this command to keep the theme updated.

Then to use the theme, you need to update the _quarto.yml file by adding the following lines to the project and format sections:

_quarto.yml

project:
  type: seedcase-theme

# ...

format: seedcase-theme-html

Connecting to hosting services

If you use this template to make a website hosted on Netlify, you need to connect the GitHub repository to Netlify. The Quarto documentation has an excellent guide on how to do this. It includes configuring Netlify to host the website and adding the NETLIFY_AUTH_TOKEN secret to the GitHub repository (or ideally at the organization level).

Note

Given that Seedcase repositories use Netlify to host any website, the NETLIFY_AUTH_TOKEN will already be available to any public repository on the Seedcase Project’s GitHub organization.

For hosting on GitHub Pages, it’s a bit easier to set up than Netlify. The Quarto documentation again has a guide on how to do this. Before you can host on GitHub Pages, you need to use Quarto to set things up for you, by running the following command:

Terminal

quarto publish github-pages

Optional

These optional next steps are very helpful for developing and refining templates. However, they are a bit more advanced than is required, so only do them if you feel comfortable enough with them.

Setting up pre-commit hooks

Pre-commit hooks are scripts that run when committing changes to a Git repository. They are incredibly useful for enforcing coding standards and catching errors early. The justfile contains a install-precommit recipe that sets up the pre-commit hooks for your project. Run it by opening a terminal within the project directory and running the following command:

Terminal

just install-precommit

This sets up the pre-commit hooks to run standard checks on your repository whenever you commit files to the history. Using pre-commit hooks as part of your workflow is even better if you connect the continuous integration service to your repository. Go to the pre-commit.ci website and follow the instructions there to connect your repository to the service. This will run the pre-commit hooks on every commit you push to the repository, including pull requests, which will ensure that the code is checked for basic issues. It will also keep the pre-commit hooks updated by creating a pull request whenever newer versions of the hooks are available.

Auto-releasing to Zenodo

If you create a release on GitHub, either manually or through a GitHub workflow, you can have that release automatically create a record on Zenodo, which is a service that allows you to archive projects and create a DOI for it.

GitHub and Zenodo have an integration that, when set up, will automatically create a Zenodo record from a GitHub release. This is useful if you want to create a DOI for your project, which will allow you or others to cite it in their work as well as provide more exposure for your project. Connecting GitHub to Zenodo is very easy, check out Zenodo’s guide on it.

Setting up GoatCounter

If you want to use GoatCounter for website visitor tracking, you need to create a GoatCounter account and set up a new site for your website. Adding a new site is very easy. Go into the “Settings” after logging into your account. Under “Sites”, click “Add new site” and fill in the form with your website’s unique name. You can use the auto-filled name in the docs/includes/site-counter.html file, which has the format of “orgname-reponame”, or you can create your own site name.