Document static site rationale
This commit is contained in:
Meta Vens
parent
e261c6da75
commit
721d942690
2 changed files with 152 additions and 10 deletions
71
README.md
71
README.md
|
|
@ -1,24 +1,70 @@
|
|||
# Pomba Branca Site
|
||||
# Pomba Branca Website
|
||||
|
||||
Static Quartz site for `pombabranca.org`, built with the shared `GameCult-Quartz` engine.
|
||||
This repository contains the Pomba Branca website for `pombabranca.org`.
|
||||
|
||||
In plain terms: the website is now a folder of ordinary text files, images, and design settings. GitHub stores those files, keeps a history of changes, and can publish the finished site as static web pages. There is no Wix editor, database, plugin marketplace, or monthly hosting platform required for the public site.
|
||||
|
||||
## Why This Exists
|
||||
|
||||
The previous website was hosted through Wix. Wix is convenient, but it means the site is tied to Wix's hosting, editor, pricing, and account access.
|
||||
|
||||
This version is a static website:
|
||||
|
||||
- It is simple HTML, CSS, images, and generated pages.
|
||||
- It can be hosted on GitHub Pages at no hosting cost while the repository is public.
|
||||
- It can also be moved to another host later without rebuilding the whole site.
|
||||
- The charity owns the content and the deployment process instead of depending on one website builder.
|
||||
- Changes can be reviewed before they go live, which is useful for a group that prefers shared decisions.
|
||||
|
||||
## What Is In This Repository
|
||||
|
||||
- `PombaBranca/` contains the actual website content: Portuguese pages, English pages, news posts, and images.
|
||||
- `PombaBranca/en/` contains the English version of the site.
|
||||
- `PombaBranca/Noticias/` and `PombaBranca/en/News/` contain the microblog/news posts.
|
||||
- `site/` contains the Pomba Branca design and configuration.
|
||||
- `scripts/` contains helper scripts for building or previewing the site.
|
||||
- `quartz-site/public/` is the generated website output. It is created by the build and is not edited by hand.
|
||||
|
||||
## How Publishing Works
|
||||
|
||||
The site is built with the shared `GameCult-Quartz` static-site engine. That engine turns the Markdown files and images in this repository into normal website files.
|
||||
|
||||
When changes are pushed to GitHub, the deploy workflow in `.github/workflows/deploy-quartz.yml` can build the site and publish it to GitHub Pages.
|
||||
|
||||
## Editing Content
|
||||
|
||||
Most content edits happen in `PombaBranca/`.
|
||||
|
||||
Examples:
|
||||
|
||||
- Portuguese homepage: `PombaBranca/index.md`
|
||||
- English homepage: `PombaBranca/en/index.md`
|
||||
- Portuguese services page: `PombaBranca/servicos.md`
|
||||
- English services page: `PombaBranca/en/services.md`
|
||||
- Portuguese news feed: `PombaBranca/Noticias/`
|
||||
- English news feed: `PombaBranca/en/News/`
|
||||
|
||||
News posts can be very small. A simple Markdown file in the news folder will appear directly in the feed as a microblog-style post. Longer articles can use frontmatter such as `description` and `article: true` so the feed shows a summary and a read-more link.
|
||||
|
||||
## Domain Notes
|
||||
|
||||
These were the domain records observed during the migration work:
|
||||
|
||||
- Registrar: GoDaddy.com, LLC
|
||||
- Authoritative DNS: `ns43.domaincontrol.com`, `ns44.domaincontrol.com`
|
||||
- Current web target: `www.pombabranca.org` CNAMEs through Wix (`pointing.wixdns.net`)
|
||||
- Previous web target: `www.pombabranca.org` pointed to Wix through `pointing.wixdns.net`
|
||||
- Planned web target: configure GoDaddy DNS so `www.pombabranca.org` CNAMEs to `gamecult.github.io`
|
||||
- Mail: Google Workspace MX records
|
||||
- Domain expiry seen in RDAP: 2026-07-29
|
||||
|
||||
## Repo Shape
|
||||
Do not change the mail records when moving the website. The website and email are separate services.
|
||||
|
||||
- `PombaBranca/`: published Markdown content and static assets
|
||||
- `site/`: site-specific Quartz overlay
|
||||
- `quartz-site/public/`: generated static output
|
||||
- `scripts/quartz/quartz.ps1`: local build/dev launcher
|
||||
The registrar can stay with GoDaddy for now. Moving registrars may save some money, but it is not necessary for launching the new website and is not worth adding extra process risk to this migration.
|
||||
|
||||
## Local Development
|
||||
|
||||
This is only needed for people working on the site design or previewing changes locally.
|
||||
|
||||
Install dependencies in the sibling engine first:
|
||||
|
||||
```powershell
|
||||
|
|
@ -26,16 +72,21 @@ cd E:\Projects\GameCult-Quartz
|
|||
npm ci
|
||||
```
|
||||
|
||||
Then run this site:
|
||||
Run a local preview:
|
||||
|
||||
```powershell
|
||||
cd E:\Projects\pombabranca-site
|
||||
.\scripts\quartz\quartz.ps1 dev
|
||||
```
|
||||
|
||||
For a production build:
|
||||
Build the production site:
|
||||
|
||||
```powershell
|
||||
.\scripts\quartz\quartz.ps1 build
|
||||
```
|
||||
|
||||
## Board-Friendly Summary
|
||||
|
||||
There is a fuller explanation in `docs/board-website-proposal.md`.
|
||||
|
||||
The short version: this move reduces recurring hosting dependence, gives Pomba Branca more control over its website, keeps changes reviewable, and still allows the site to be moved elsewhere later if needed.
|
||||
|
|
|
|||
91
docs/board-website-proposal.md
Normal file
91
docs/board-website-proposal.md
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
# Proposal: Move Pomba Branca From Wix to a Static Website on GitHub Pages
|
||||
|
||||
## Summary
|
||||
|
||||
Pomba Branca can replace the current Wix website with a modern static website hosted through GitHub Pages.
|
||||
|
||||
This means the public website is made from simple files: text pages, images, and design settings. GitHub stores those files, keeps a record of changes, and can publish the finished website online.
|
||||
|
||||
For a small charity website, this is a good fit. The site does not need bookings, payments, private member accounts, or a complicated database. It mainly needs clear public information, bilingual support, news updates, contact details, and a stable place to live.
|
||||
|
||||
## Why Move Away From Wix?
|
||||
|
||||
Wix is useful when someone needs a visual website builder and does not want to touch files. The tradeoff is dependence on Wix:
|
||||
|
||||
- The site is tied to Wix's editor and hosting.
|
||||
- Costs can continue even for a small public-information site.
|
||||
- Moving away later can be awkward.
|
||||
- Access depends on knowing who owns the Wix account.
|
||||
- Design and structure are limited by the platform.
|
||||
|
||||
For Pomba Branca, the website is mostly public information. That makes a static site simpler, cheaper, and easier to preserve.
|
||||
|
||||
## What GitHub Pages Gives Us
|
||||
|
||||
GitHub Pages can host static websites at no hosting cost when the repository is public.
|
||||
|
||||
For a charity site, keeping the website code public is usually acceptable because the website content is already public. There is no private client data, payment information, or confidential internal system in the repository.
|
||||
|
||||
The advantages are:
|
||||
|
||||
- No normal hosting bill for the public website.
|
||||
- The site files are owned and controlled directly.
|
||||
- Every change has a history.
|
||||
- Updates can be reviewed before publication.
|
||||
- The site can be moved to another host later if needed.
|
||||
- The website is not locked into Wix.
|
||||
|
||||
## Governance Benefits
|
||||
|
||||
This approach is well suited to an organisation that does not want one person making unilateral decisions.
|
||||
|
||||
Instead of changing a live website directly, changes can be proposed, reviewed, and then published. This gives the board or trusted volunteers a clearer process:
|
||||
|
||||
1. Someone proposes a content or design change.
|
||||
2. The change can be reviewed before it goes live.
|
||||
3. The change is approved and merged.
|
||||
4. GitHub publishes the updated website.
|
||||
|
||||
This creates a written record of what changed, when it changed, and who approved it.
|
||||
|
||||
## Practical Benefits
|
||||
|
||||
The new site supports:
|
||||
|
||||
- Portuguese and English pages.
|
||||
- A simple news/microblog feed.
|
||||
- Static image assets.
|
||||
- Fast page loading.
|
||||
- Low maintenance.
|
||||
- No dependency on Wix hosting.
|
||||
- Future hosting flexibility.
|
||||
|
||||
Because the site is static, there is less that can break. There is no database to maintain and no plugin stack to keep patched.
|
||||
|
||||
## Cost Position
|
||||
|
||||
The current situation includes paying for a hosted website platform for a small public-information site.
|
||||
|
||||
With GitHub Pages, GitHub handles the hosting for a public static site. The main ongoing cost should be the domain name itself, not a separate website hosting subscription.
|
||||
|
||||
The domain and email can remain separate. Moving the website does not require moving Google Workspace email.
|
||||
|
||||
There is also no need to move the domain away from GoDaddy as part of this project. A different registrar may be cheaper, but transferring the domain is a separate administrative task and not required for the website launch. The practical plan is to keep the domain at GoDaddy and update GoDaddy DNS so `www.pombabranca.org` points to `gamecult.github.io`.
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
There is a learning curve. Editing files is different from using Wix. This can be mitigated by having a technical maintainer or volunteer handle publishing, while board members review content in plain language.
|
||||
|
||||
GitHub Pages is best for static public sites. If Pomba Branca later needs private accounts, payments, bookings, or a full CRM, those should be handled by dedicated services rather than bolted onto the website.
|
||||
|
||||
The repository is public. This is acceptable for public website content, but private documents, private contact lists, or sensitive internal materials should not be stored here.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Move the public Pomba Branca website from Wix to the static GitHub Pages site.
|
||||
|
||||
This gives Pomba Branca more control, reduces avoidable hosting dependence, supports bilingual public communication, and creates a clearer review process for future changes.
|
||||
|
||||
The result is a website that is simpler, cheaper to host, easier to preserve, and not locked to a single website-builder platform.
|
||||
|
||||
For the domain, keep the current GoDaddy registration for now. The only required DNS change is to point the website address at GitHub Pages while leaving email records untouched.
|
||||
Reference in a new issue