README: update
This commit is contained in:
IkiWiki
parent
a65bf15f2b
commit
ca8f37eb4b
GPG key ID:
D62A472A4AA7D541
1 changed files with 56 additions and 73 deletions
129
README.md
129
README.md
|
|
@ -1,99 +1,82 @@
|
|||
|
||||
# ayakael.net
|
||||
Upstream: https://ayakael.net/forge/ayakael.net/actions
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
**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.
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## 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 <name>`
|
||||
- `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
|
||||
|
|
|
|||
Loading…
Reference in a new issue