1. Goal & Big Picture

• You write and edit markdown docs in this WSL-based VS Code workspace.
• The workspace folder is a Git repo connected to GitHub.
• GitHub Pages takes the repo and turns it into a static HTML site.
• Your custom domain (e.g. docs.yourdomain.com) points at the GitHub Pages site.

High-level flow:

VS Code (WSL) → Git commits → GitHub repo → GitHub Pages → Custom domain

2. Connect This Workspace to GitHub

Prereqs

• Git installed inside WSL (git --version).
• GitHub account and basic login ready.

Initial Git setup in WSL (once)

• Set your name and email:
  • git config --global user.name "Your Name"
  • git config --global user.email "you@example.com"
• Decide how you authenticate to GitHub:
  • Easiest: HTTPS + personal access token (PAT).
  • Nicer long-term: SSH keys (ssh-keygen in WSL, add public key to GitHub).

Turn this workspace into a repo

From /home/bb/_vsc-dev1 wsl workspace:

• git init
• git add *.md (or git add . if you want the whole workspace tracked)
• git commit -m "Initial docs"

Create GitHub repo and link it

• On GitHub: create a new repo (e.g. homestuff-docs), no need to add files there.
• Back in WSL:
  • git remote add origin https://github.com/USERNAME/homestuff-docs.git
  • git branch -M main
  • git push -u origin main

Now your docs in this workspace are versioned and mirrored on GitHub.

3. Organize Docs for GitHub Pages

Simplest approach: use a docs/ folder and let GitHub Pages publish from it.

Suggested layout

• Repo root (in WSL):
  • docs/
    • index.md (landing page)
    • wsl-ebay-report.md
    • WSL_ebay-automations.md
    • other markdown docs…

How to adapt this workspace

• Option A: Move these files into a docs/ folder under the repo root.
  • Create docs/ and move:
    • wsl-ebay-report.md
    • WSL_ebay-automations.md
    • any other docs you want public.
• Option B: Keep your current file layout and later add a small build step that copies them into docs/ before pushing.

For a first pass, Option A is simpler.

4. Enable GitHub Pages for the Repo

Once your repo is on GitHub and contains a docs/ folder:

• In your GitHub repo, go to: Settings → Pages.
• Under Source, select:
  • Branch: main
  • Folder: /docs
• Save.

GitHub will:

• Build a simple static site from your markdown using its default Jekyll engine.
• Publish it at something like:
  • https://USERNAME.github.io/homestuff-docs/

You can check logs and status in the Pages section if something fails.

5. Choosing How Fancy You Want the Site

You have three basic levels of complexity:

For now, using plain GitHub Pages or MkDocs is enough:

• Plain Pages: keep .md files in docs/ and let GitHub handle HTML.
• MkDocs: locally run mkdocs build to produce static HTML into site/ or docs/, then push.

6. Custom Domain Setup

Once the GitHub Pages site works on the default URL:

Step 1 – Decide your domain

• Example: docs.yourdomain.com (subdomain) or yourdomain.com itself.

Step 2 – Configure on GitHub

• Go to Settings → Pages → Custom domain.
• Enter your desired domain (e.g. docs.yourdomain.com) and save.
• GitHub will create or expect a CNAME file in the repo with that domain name.

Step 3 – Configure DNS at your domain registrar

• Log into your domain provider (Namecheap, Cloudflare, etc.).
• Add a DNS record pointing your domain to GitHub Pages:
  • For a subdomain (docs.yourdomain.com):
    • Type: CNAME
    • Name/Host: docs
    • Value/Target: USERNAME.github.io
  • For a root domain (yourdomain.com):
    • Use the A/ALIAS records GitHub recommends in their docs.
• Wait for DNS to propagate (often a few minutes to a few hours).

Once DNS and the CNAME are aligned, visiting your custom domain should show the GitHub Pages site.

7. Daily Workflow from VS Code

From this WSL workspace:

• Edit or add markdown docs (wsl-ebay-report.md, WSL_ebay-automations.md, etc.).
• Make sure they live in the folder GitHub Pages is publishing from (docs/ if you follow the suggested layout).
• Run:
  • git status (see changes)
  • git add <files> or git add .
  • git commit -m "Update eBay workflow docs"
  • git push
• GitHub Pages automatically rebuilds and deploys.
• After a short delay, refresh your site at your custom domain to see updates.

This gives you a simple, repeatable path: write in VS Code → commit → push → site updates.