From ca8f37eb4b5927400172993a905eaa748f4b3fa8 Mon Sep 17 00:00:00 2001 From: IkiWiki Date: Sun, 25 Aug 2024 20:31:48 -0400 Subject: [PATCH] README: update --- README.md | 129 ++++++++++++++++++++++++------------------------------ 1 file changed, 56 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index af49be3..4a7de96 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,82 @@ -![Build Status](https://gitlab.com/pages/ikiwiki/badges/master/build.svg) +# ayakael.net +Upstream: https://ayakael.net/forge/ayakael.net/actions ---- +![Build Status](https://ayakael.net/forge/ayakael.net/badges/workflows/pages.yaml/badge.svg) +![Push Status](https://ayakael.net/forge/ayakael.net/badges/workflows/push.yaml/badge.svg) -Example [ikiwiki] website using GitLab Pages. +## Forgejo Actions -Learn more about GitLab Pages at https://pages.gitlab.io and the official -documentation https://docs.gitlab.com/ce/user/project/pages/. +This project's static Pages are built by Forgejo Actions, following the steps +defined in [`.forgejo/workflows/pages.yaml`](.forgejo/workflows/pages.yaml). +That builds this website using ikiwiki, and pushes the build artifacts to the +`public` branch. ---- +The `public` branch has its own workflow following steps defined in +[`forgejo/workflows/push.yaml`](https://ayakael.net/forge/ayakael.net/src/branch/public/.forgejo/workflows/push.yaml) +that uploads the artifacts to a remote HTTP server for deployment in +production. This workflow is automatically updated from `main` so that `public` +should never be manually modified. - - -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* +The deployment is done by a simple remote git push via SSH to a non-bare repo +where `git config receive.denyCurrentBranch` is set as `updateInstead`. This +allows this repo to be checked out as `public`, allowing it to be a root for +your favorite HTTP server. -- [GitLab CI](#gitlab-ci) -- [Building locally](#building-locally) -- [GitLab User or Group Pages](#gitlab-user-or-group-pages) -- [Did you fork this project?](#did-you-fork-this-project) -- [Troubleshooting](#troubleshooting) +The following secrets are expected to be set for operation: +* PAGES_PRIVKEY: SSH private key that is used to push to the HTTP server's git +repo +* PAGES_TOKEN: Forgejo application token used to push to `public` branch. - - -## GitLab CI - -This project's static Pages are built by [GitLab CI][ci], following the steps -defined in [`.gitlab-ci.yml`](.gitlab-ci.yml): - -```yaml -image: elecnix/ikiwiki - -before_script: - - apt-get install -y git - - git submodule init - - git submodule update - -test: - stage: test - script: - - ikiwiki --setup ikiwiki.setup --libdir themes/ikistrap/lib - only: - - branches - - tags - -pages: - stage: deploy - script: - - ikiwiki --setup ikiwiki.setup --libdir themes/ikistrap/lib - artifacts: - paths: - - public - only: - - master -``` - -We are using a theme based on Bootstrap 4 using submodules, and in order to -enable the theme plugin, we must pass the `libdir` parameter. +The following variables are expected to be set for operation: +* PAGES_TARGET: SSH target for HTTP server's git repo, following this format: +user@example.net:/path/to/http/repo ## Building locally To work locally with this project, you'll have to follow the steps below: 1. Fork, clone or download this project -1. [Install][] ikiwiki -1. Clone the submodules: `git submodule init && git submodule update` -1. Generate the website: `ikiwiki --setup .ikiwiki/ikiwiki.setup --libdir themes/ikistrap/lib` -1. Preview your project: open `public/index.html` in a browser +1. Install ikiwiki: + * [mac][] + * [linux][] + * [source][] +1. Generate the website: `ikiwiki --setup ikiwiki.setup` +1. Start http-server: `./test-server.sh` +1. Preview your project: open 127.0.0.1:8080 in your browser Read more at ikiwiki's [documentation][]. -## GitLab User or Group Pages +## Contributing -To use this project as your user/group website, you will need one additional -step: just rename your project to `namespace.gitlab.io`, where `namespace` is -your `username` or `groupname`. This can be done by navigating to your -project's **Settings**. +1. Fork the main ayakael.net repo. -Read more about [user/group Pages][userpages] and [project Pages][projpages]. +2. Checkout the forked repository. -## Did you fork this project? + - `git clone ssh://git@ayakael.net/$USER/ayakael.net` + - `cd ayakael.net` -If you forked this project for your own use, please go to your project's -**Settings** and remove the forking relationship, which won't be necessary -unless you want to contribute back to the upstream project. +3. Make your changes. -## Troubleshooting +4. Do local build. -1. CSS is missing! That means two things: + - `ikiwiki --setup ikiwiki.setup` - Either that you have wrongly set up the CSS URL in your templates, or - your static generator has a configuration option that needs to be explicitly - set in order to serve static assets under a relative URL. +5. Fix any errors that come up and rebuild until it works locally. + +6. Commit the changes to the git repo in a git branch + + - `git checkout -b ` + - `git add` changes + - `git commit -m 'content/index: descriptive description'` + - `git push` + +7. Create a merge request with your changes by following link in server response. + +8. Once the tests in the merge-request pass, and reviewers are happy, your changes + will be merged. -[ci]: https://about.gitlab.com/gitlab-ci/ [ikiwiki]: https://ikiwiki.info/ -[install]: https://ikiwiki.info/install/ +[source]: https://ikiwiki.info/install/ +[linux]: https://ikiwiki.info/setup/ +[mac]: https://ikiwiki.info/tips/ikiwiki_on_mac_os_x/ [documentation]: https://ikiwiki.info/ -[userpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#user-or-group-pages -[projpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#project-pages