Skip to main content

Getting Started

To start using Emanates, you need to create a repository from the template repository and then setup a few things from there.

Creating a repo#

Here's how to create a repo in order to start using Emanates:

  1. Click on this link to generate a repo.
  2. Select a name of the repository.
  3. Select visibility of the repo, Emanates works with private repos as well.
tip

Alternative to the first step, you can go to the Emanates Repo and click on Use Template.

After creating the repo#

Once the repo is created, you need to setup a few more things.

Setup GitHub Secrets#

In order for Emanates to fetch all the posts in the repo, we need access to the repo as well (because your repo might be private). Thus, we require a GitHub Token that will be used while building the page.

This token needs to be saved as a repository secret in order for the workflow to be able to access it.

You need to create a GitHub personal access token (PAT) with access to your repository and access to github container registry. Read here on how to create a personal access token

Name it EMANATES_TOKEN and save it as a secret in the current repo. You can read here on how to create a repository secret.

warning

Don't get rid of the token yet, you might need it depending on your deployment option.

info

This is important because the build will actually run on a GitHub pipeline so Emanates will use GitHub's API to fetch the issues and accordingly build the static site.

Configure Emanates#

We try to do almost everything by ourselves but a few things require user input, such as the baseUrl of the blog (important to show on the navbar).

Thus, there needs to be an way to configure Emanates. This can be done through the Emanates Configuration file (.emanates.js) which should be present at the root of the repository.

Check configuration to learn more about how to configure

info

This step is optional however it is recommended to do this in order to get good SEO. Also, nobody likes to use the tool's logo as the logo of their site!

Setup the workflow#

One important step is to let Emanates know where to deploy the site once it's built. There are various options for this, you might want to deploy your blog to a personal server, or perhaps to Netlify. In any case, that is done through the workflow file present in the .github/workflows/ directory.

We already setup a default workflow there, you just need to setup some lines as to where to deploy the static website once it's built.'

Check deployment options for more details on that

danger

This is a required step. Emanates will not work unless you setup a deployment option.