How to deploy a Next.js static site to Github Pages.



[Github Pages](https://pages.github.com/) is a great place to deploy static [Next.js](/post/what-is-nextjs/) sites.

## Setup Next.js

As of `next@3`, a static export of your Next.js site is possible.

This is accomplished with:

```bash
next build && next export
```

When you export, you can specify the output directory with `-o`.  Github pages has an option of serving the `docs/` directory of your `master` branch, so we'll setup for that.  Adjust the command to be:

```bash
next build && next export -o docs
```

## Setup Custom Domain

To prep your Github Pages site to be served by a custom domain, you'll need to first buy the domain, [setup the DNS](https://help.github.com/articles/quick-start-setting-up-a-custom-domain/).

For an [example project](https://github.com/jaketrent/electron-course), my DNS setup has two entries:

```txt
CNAME electroncourse.com jaketrent.github.io
CNAME www                electroncourse.com
```

Connect your custom domain to your Github Pages site by adding a file to `docs/CNAME` with the contents of your custom domain:

```txt
electroncourse.com
```

You'll notice that this `CNAME` file is in the `docs/` directory, which is the target of the Next.js `export` command.  `export` will blow the directory away, removing your `CNAME` file.  We want to make sure we don't lose it after an export.

## NoJekyll Support

Github pages are processed by [Jekyll](https://jekyllrb.com/) by default.  In our case, the directories Next.js builds by default include a `_next` directory with all the built JavaScript assets.  In order to make those findable in our deployed site, we need to [add a special file](https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/) called `.nojekyll` inside the `docs/` directory.  

We'll also need to take care not to remove this file when running a `next export` command.

## All-in-one Deploy Script

So here is an all-in-one deploy script for building, exporting, preserving the `CNAME` and `.nojekyll` files, committing, and pushing your content to the server.  If we put this in `package.json`:

```json
"scripts": {
  "deploy": "next build && next export -o docs && git checkout -- docs/CNAME && git checkout -- docs/.nojekyll && git add docs && git commit -m \"chore: regen site\" && git push origin master"
}
```

Epic!  Then we can run it with: `npm run deploy`.

## Setup Repo for Github Pages

Now go to your [repo](https://github.com/jaketrent/electron-course) on Github and go to the "Settings" tab.  Under that tab, find the section labeled "Github Pages".  Choose the "Source" option of: `master branch /docs folder`.

![github docs directory](https://i.imgur.com/6c8yWY6.jpg)

This will serve your page from that `docs/` directory.

To see if your page is working, visit your Github Pages URL, eg [`jaketrent.github.io/electron-course`](http://jaketrent.github.io/electron-course).  If the DNS is working, you'll get a redirect to your custom domain, [`electroncourse.com`](http://electroncourse.com).

You've now deployed your Next.js site to Github Pages!

What else have you done to make this process better?

How to deploy a Next.js static site to Github Pages.

Deploy Next.js to Github Pages

Edit your Github repo's wiki in your favorite editor.



## Github Wiki

You likely have many of your code repos on Github.  They have this nice feature of a built-in wiki per repository, so you can put helpful documents right next to the code.  

![github wiki web interface](https://i.imgur.com/5tIy3O3.jpg)

Perhaps you have wondered where these docs are stored, or perhaps you have wished that you could edit these files outside the web interface.  The web interface is nice and convenient, but it might not have the editing power you want if you're going through lots of documentation edits.

## Wiki Repo

Each wiki has its own git repository.  It's named exactly the same as your source code repository, but it has a `.wiki` suffix.  

If you clone your code with this command:

```bash
git clone git@github.com:jaketrent/container-ship.git
```

Your wiki clone command would be:


```bash
git clone git@github.com:jaketrent/container-ship.wiki.git
```

## Editing in Vim

Once you're cloned, all you have left to do is edit.  You can use your favorite editor.  I've been enjoying [Spacemacs](/tags/spacemacs/) lately, but you can use `vim` or something similar.

Change to the wiki directory and start editing files:

```bash
cd container-ship.wiki
vim Home.md
```

When done editing, commit and push as normal in a git repo.  You will see your changes reflected in the web interface.

## Special Files

There are a few specially-named files that could be useful to you:

- `Home.md` - this is the default entry point for a wiki.  When you click the 'Wiki' tab in the web interface of Github, you go here.
- `_Sidebar.md` - if you want a sidebar navigation element in your wiki, you can put navigational (or whatever) content here
- `_Footer.md` - like the Sidebar, just at the bottom of each wiki page.

![wiki sidebar](https://i.imgur.com/EEWO6Wl.jpg)

## File Placement

When you edit your wiki in the web browser, it drops all the wiki pages' `*.md` files in the wiki root directory.  This is fine and simple.  

If you have a lot of content or want to organize things for easier editing later, you can create arbitrary directories and naming to match your organizational theme.  For instance, you could create subdirectories for `docs`, `api`, and `guides` -- whatever you like.

Then when you link to pages using the Github-flavored markdown language, you can disregard the subdirectory paths.  For instance, if you put the file in `api/users.md`, you could link to that page by using just the filename: `[[user]]`.

What other interesting benefits have you found to editing Github wikis offline?

Edit your Github repo's wiki in your favorite editor.