|
1 | | -# Yawar Hussain — personal site |
| 1 | +# Yawar Hussain — personal website |
2 | 2 |
|
3 | | -A small Python static-site generator, no framework. Same design as before |
4 | | -(craftzdog-homepage-inspired), now split into real pages so adding a blog |
5 | | -post is a one-file change. |
| 3 | +Plain HTML/CSS/JS, no build step, no framework. Design based on Takuya |
| 4 | +Matsuyama's [craftzdog-homepage](https://github.com/craftzdog/craftzdog-homepage) |
| 5 | +(MIT-licensed source) — the 3D voxel-dog mascot is CC BY-NC-ND on that repo |
| 6 | +("you can't reuse it on your website"), so it's not included here; the photo |
| 7 | +and footprint icon replace it. |
6 | 8 |
|
7 | | -## Adding a blog post |
8 | | - |
9 | | -1. Copy `content/posts/_template.md` to `content/posts/YYYY-MM-DD-your-slug.md`. |
10 | | -2. Fill in `Title`, `Date`, `Summary`, and write the post body in Markdown below the blank line. |
11 | | -3. `python build.py` (or just `git push` — see Deploying below). |
12 | | - |
13 | | -That's it — no other file changes, no registering the post anywhere. The |
14 | | -filename becomes the URL (`/blog/your-slug/`), and it's sorted onto the Blog |
15 | | -page automatically by date. |
16 | | - |
17 | | -**Adding pictures to a post:** drop the image into `images/` (e.g. |
18 | | -`images/my-post-photo.jpg` — anything in there gets published as-is) and |
19 | | -reference it in the post's Markdown as: |
20 | | - |
21 | | -```markdown |
22 | | - |
23 | | -``` |
24 | | - |
25 | | -The `../../` is because a post page lives two folders deep |
26 | | -(`blog/<slug>/index.html`); it's the same for every post, regardless of |
27 | | -slug. Standard Markdown image syntax, so normal image sizes/formats (jpg, |
28 | | -png, gif, svg) all work. |
29 | | - |
30 | | -## Editing everything else |
31 | | - |
32 | | -- `data.py` — your CV content: employment, fieldwork, projects, editorial |
33 | | - roles, education, conferences, publications. Plain Python lists/dicts. |
34 | | -- `theme.py` — colours, fonts, CSS, icons, the page shell (nav/footer). You |
35 | | - shouldn't need to touch this for content changes. |
36 | | -- `build.py` — the page layouts themselves (what goes on Home/Works/Fieldwork/Publications). |
37 | | -- `images/profile.jpg` — your photo. |
38 | | - |
39 | | -## Running it locally |
| 9 | +## Folder structure |
40 | 10 |
|
41 | 11 | ``` |
42 | | -pip install -r requirements.txt |
43 | | -python build.py |
| 12 | +index.html the page itself (About / Works / Publications, one file, |
| 13 | + JS shows/hides the right section — no page reloads) |
| 14 | +assets/css/main.css all styling, incl. the light/dark theme toggle |
| 15 | +assets/js/main.js page behaviour: theme toggle, mobile menu, section routing |
| 16 | +images/profile.jpg your photo (About section) |
44 | 17 | ``` |
45 | 18 |
|
46 | | -That's it — `dist/index.html` opens directly in a browser (double-click it, |
47 | | -or `open dist/index.html`), no server needed. Every link and asset in the |
48 | | -site is a relative path, so it works the same over `file://` as it does once |
49 | | -deployed. (A local server also works if you prefer one: `python -m |
50 | | -http.server -d dist 8000`.) |
| 19 | +## Editing content |
51 | 20 |
|
52 | | -`build.py` writes everything into `dist/` (git-ignored — it's generated, not |
53 | | -source). |
| 21 | +Open `index.html` and search for the section you want: |
| 22 | +- `id="page-home"` — About page (intro line, bio timeline, interests, links) |
| 23 | +- `id="page-works"` — Works page (employment, projects, editorial, education, conferences) |
| 24 | +- `id="page-fieldwork"` — Fieldwork page (field deployments, grid of entries) |
| 25 | +- `id="page-blog"` — Blog page (empty state for now — add post cards here later) |
| 26 | +- `id="page-pubs"` — Publications page (grouped, collapsible by topic) |
54 | 27 |
|
55 | | -## Deploying on GitHub Pages |
56 | | - |
57 | | -This repo includes `.github/workflows/deploy.yml`, which builds the site and |
58 | | -publishes it automatically on every push to `main`. One-time setup: |
| 28 | +## Swapping the photo |
59 | 29 |
|
60 | | -1. Push this repo to GitHub — either as `<your-username>.github.io` (a user |
61 | | - site at the domain root) or as any other repo name (a project site at |
62 | | - `<username>.github.io/reponame/`). Both work with no configuration: every |
63 | | - link and asset path in the site is relative, not root-absolute, so it |
64 | | - doesn't care which path it's served from. |
65 | | -2. Repo Settings → Pages → **Source: GitHub Actions**. |
66 | | -3. Push to `main`. The Action builds with `python build.py` and deploys |
67 | | - `dist/` — no need to commit generated HTML, and no Ruby/Jekyll involved |
68 | | - (there's a `.nojekyll` file in the output so GitHub Pages serves it as-is). |
| 30 | +Overwrite `images/profile.jpg` with a similar-ish aspect ratio image (it's |
| 31 | +cropped into a circle, so a centred headshot works best) — no HTML changes |
| 32 | +needed. |
69 | 33 |
|
70 | | -After that, writing a post is: add the Markdown file, commit, push — the |
71 | | -site rebuilds and redeploys on its own in ~30 seconds. |
| 34 | +## Attribution |
72 | 35 |
|
73 | | -## On "Jekyll" vs Python options |
| 36 | +Per the reference project's license, the footer keeps a credit link to |
| 37 | +https://www.craftz.dog/ — please leave it in place if you keep using this design. |
74 | 38 |
|
75 | | -GitHub Pages' *native*, zero-build option is Jekyll — but Jekyll is Ruby, not |
76 | | -Python, so it's not what you asked for. If you want a fuller Python blogging |
77 | | -engine instead of this hand-rolled one, **Pelican** is the closest |
78 | | -equivalent (Markdown/reST posts, Jinja2 themes, RSS/Atom feeds, tags and |
79 | | -categories built in, and a documented GitHub Pages deploy path via |
80 | | -`ghp-import` or the same Actions approach used here). It's more powerful but |
81 | | -also more machinery — a theme to install or write, a settings file, a |
82 | | -plugin system — for what's currently a five-page personal site. |
| 39 | +## Deploying on GitHub Pages |
83 | 40 |
|
84 | | -This repo goes with the smaller option on purpose: ~250 lines of Python |
85 | | -total, one dependency (`Markdown`), and the exact design you already have. |
86 | | -If the blog grows into the main thing on the site and you want tags, feeds, |
87 | | -or pagination, migrating this content into Pelican later is a straightforward |
88 | | -step up — the Markdown posts themselves need no changes. |
| 41 | +1. Create a repo named `<your-username>.github.io`. |
| 42 | +2. Push this whole folder's contents to the repo root (so `index.html` sits |
| 43 | + at the top level, not inside a subfolder). |
| 44 | +3. Settings → Pages → should already serve from `main` / root for this repo |
| 45 | + name. Wait a minute, then visit `https://<your-username>.github.io`. |
0 commit comments