Template for a static website using Sphinx and GitHub Pages

Instructions

1. Create new repository based on this template

Create a template based on this repository by clicking on the "Use this template" button, see instructions here

• now you are already publish the site which looks identical to the template site (see it here)
• jump to step 5 to do that directly.

2. Open in GitHub Codespaces (or locally)

• go to github.com/codespaces
• create a new codespace using the forked repository

If you are done, remember to delete the codespace to not see your free credit or money wasted. Also inactive (stopped) codespaces use storage for the last 30 days.

3. Edit files

• update in conf.py at least the author, project and copyright information at the top
  • also update two urls to your repository:

   "github_url": "https://github.com/enryh/",
   "repository_url": "https://github.com/enryh/notes_template",

• write something about you in about.md
• write articles in folder_topic/article_topic.md
• update the index.md file to include new files
• use pandoc to convert your previous files into markdown or reStructuredText

4. Build the site locally

Have look at .github/workflows/build_website.yaml to see how the site is built if you are interested.

• Open a terminal (GitHub Codespaces)
• install required packages from requirements.txt:

  pip install -r requirements.txt

• build the site (you could set an alias if you want):

  sphinx-build -n -W --keep-going -b html ./ ./_build/

  in case the command is not found, try:

   python -m sphinx -n -W --keep-going -b html ./ ./_build/

• open the site in a browser:
  • install "Live Preview" extension in Visual Studio Code
  • open the _build/index.html file in the browser (right-click, "Show Preview")

5. Publish the site

Follow these instructions to publish the website using GitHub Pages.

• Select the gh-pages branch as the source for the GitHub Pages site (currently step 7)