# GitHub Pages

1. In VSCode workspace settings set `"foam.edit.linkReferenceDefinitions": "withoutExtensions"`
2. Execute the “Foam: Run Janitor” command from the command palette.
3. [Turn **GitHub Pages** on in your repository settings](https://guides.github.com/features/pages/).
   - The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates.
   - GitHub Pages is built on [Jekyll](https://jekyllrb.com/), so it supports things like permalinks, front matter metadata etc.

## How to publish locally

If you want to test your published foam, follow the instructions:

- <https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll>
- <https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll>

Assuming you have installed ruby/jekyll and the rest:

- `touch Gemfile`
  - open the file and paste the following:

```
source 'https://rubygems.org'

gem "github-pages", "VERSION"
```

replacing `VERSION` with the latest from <https://rubygems.org/gems/github-pages> (e.g. `gem "github-pages", "209"`)

- `bundle`
- `bundle exec jekyll 3.9.0 new .`
- edit the `Gemfile` according to the instructions at [Creating Your Site](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll#creating-your-site) Point n.8
- `bundle exec jekyll serve`

## Other templates

There are many other templates which also support publish your foam workspace to github pages

* gatsby-digital-garden
  * [repo](https://github.com/mathieudutour/gatsby-digital-garden)
  * [demo-website](https://mathieudutour.github.io/gatsby-digital-garden/)
* foam-mkdocs-template
  * [repo](https://github.com/Jackiexiao/foam-mkdocs-template)
  * [demo-website](https://jackiexiao.github.io/foam/)
* foam-jekyll-template
  * [repo](https://github.com/hikerpig/foam-jekyll-template)
  * [demo-website](https://hikerpig.github.io/foam-jekyll-template/)

[[todo]] [[good-first-task]] Improve this documentation