Create your own digital garden on Github
Sunday 6 October 2024
Edit on Github

Create a Repository

Assuming your user name on github is user-name:

  1. Create a repository in your account called user-name.github.io : https://github.com/new
  2. Go to repository Settings (last tab on top of the repository)
  3. Go to Pages from the sidebar under Code and automation
  4. Under Build and deployment > Source choose Github Actions

Create A Home page

  1. Go to your repository Code page (first tab at the top of the repository)
  2. Click Add file > Create new file
  3. Name your file: index.md
  4. Add any content to your file. for example: Hello world!
  5. Click Commit new file

Add Github workflow

  1. Go to your repository Code page
  2. Click Add file > Create new file
  3. Name your file .github/workflows/xlog.yml
  4. Add The following content to your file
 1name: Xlog
 2
 3on:
 4  push:
 5    branches: [ "master" ]
 6
 7  # Allows you to run this workflow manually from the Actions tab
 8  workflow_dispatch:
 9
10permissions:
11  contents: read
12  pages: write
13  id-token: write
14
15concurrency:
16  group: "pages"
17  cancel-in-progress: true
18
19jobs:
20  build:
21    runs-on: ubuntu-latest
22
23    steps:
24      - uses: actions/checkout@v4
25        with:
26          fetch-depth: 0
27
28      - name: Allow non-ASCII character
29        run: git config core.quotepath false
30
31      - name: restore timestamps
32        uses: chetan/git-restore-mtime-action@v1
33
34      - name: Install xlog
35        env:
36          XLOG_VERSION: v1.6.6
37        run: |
38          curl -vvv --location -o ../xlog.tar.gz https://github.com/emad-elsaid/xlog/releases/download/${XLOG_VERSION}/xlog-${XLOG_VERSION}-linux-amd64.tar.gz
39          tar -xvf ../xlog.tar.gz -C ..          
40
41      - name: Build
42        run: |
43          ../xlog \
44          --build . \
45          --sitename "user-name"
46          rm *.md
47          chmod -R 0777 .          
48
49      - name: Upload GitHub Pages artifact
50        uses: actions/upload-pages-artifact@v3.0.1
51        with:
52          path: .
53
54  deploy:
55    environment:
56      name: github-pages
57      url: ${{ steps.deployment.outputs.page_url }}
58    runs-on: ubuntu-latest
59    needs: build
60    steps:
61      - name: Deploy to GitHub Pages
62        id: deployment
63        uses: actions/deploy-pages@v4
  1. if your main branch name is different than master please change it in the previous file.
  2. Make sure you replace any occurrence of user-name with your user name.
  3. Click Commit new file
  4. Go to Actions tab. you should find a run in progress. After it completes move to the next step.

Visiting your digital garden

  • Now your digital garden should be available under user-name.github.io
  • Visit the previous URL to make sure everything works
  • If the page doesn’t appear with Hello world! content (or the content you wrote) then something is wrong with the previous steps.

Writing new pages

  1. When you want to add a new page to your garden add the file in your repository and make sure it’s in .md (Markdown) format.
  2. After Github finishes building the page should be served as HTML with the same name without .md extension
  3. For example about.md will be served as /about
  4. keep your files names meaningful. as Xlog will autolink pages together by the file name.
  5. so in any page when you have the word about in the text, Xlog will convert it to a link to the about page.

Backlinks