138 lines
3.9 KiB
Markdown
138 lines
3.9 KiB
Markdown
# Anarchy Planet web site
|
|
|
|
This repo includes markdown files for [the Anarchy Planet web
|
|
site](https://anarchyplanet.org/) and tools to generate a static
|
|
HTML site from the source files.
|
|
|
|
## Contributing
|
|
|
|
If you are familiar with editing markdown and using git, you should
|
|
already be able to figure out how to contribute. If not, or if you need a
|
|
refresher, keep reading.
|
|
|
|
There are two methods for contributing: direct write, and pull request. Direct
|
|
write is best if you are already known in Anarchy Planet, and pull request is
|
|
best if you are a newcomer.
|
|
|
|
### Direct write
|
|
|
|
#### Prerequisites
|
|
|
|
You only have to do these steps once to get set up.
|
|
|
|
Register an account on https://git.anarchyplanet.org.
|
|
|
|
[Request](https://redmine.anarchyplanet.org/projects/anarchy-planet-support/issues/new)
|
|
write access to [this
|
|
repository](https://git.anarchyplanet.org/AnarchyPlanet/anarchyplanet-site).
|
|
|
|
[Install a git client](https://git-scm.com/downloads).
|
|
|
|
Configure git:
|
|
|
|
```
|
|
git config --global user.name <username>
|
|
git config --global user.email <email>
|
|
```
|
|
|
|
Clone this repository.
|
|
|
|
```
|
|
mkdir ~/projects
|
|
cd ~/projects
|
|
git clone https://git.anarchyplanet.org/AnarchyPlanet/anarchyplanet-site.git
|
|
```
|
|
|
|
#### Making an edit
|
|
|
|
First make sure your git repository is up to date:
|
|
|
|
```
|
|
git pull
|
|
```
|
|
|
|
Edit the `.md` files in your preferred editor. They are written in markdown,
|
|
which comes in different flavors. You you can [get an intro to markdown
|
|
here](https://www.markdownguide.org/) or read the syntax of the markdown flavor
|
|
we use [here](https://kristaps.bsd.lv/lowdown/lowdown.5.html).
|
|
|
|
Change directory to the repository and commit your changes:
|
|
|
|
```
|
|
cd ~/projects/anarchyplanet-site
|
|
git add -p
|
|
git commit
|
|
```
|
|
|
|
When you do `git commit`, git will open an editor for you to write a commit
|
|
message. Write a short summary of the changes you made.
|
|
|
|
Push your changes:
|
|
|
|
```
|
|
git push origin master
|
|
```
|
|
|
|
All done!
|
|
|
|
### Pull request
|
|
|
|
If you don't have direct write access, you can make a pull request instead.
|
|
Follow the "Direct write" instructions, but with the following differences:
|
|
|
|
* Do not request write access. Instead, visit [this
|
|
repository](https://git.anarchyplanet.org/AnarchyPlanet/anarchyplanet-site)
|
|
in your browser and click the green fork button next to the branch label.
|
|
* When you clone, clone your fork.
|
|
* After you push your changes, visit [this
|
|
repository](https://git.anarchyplanet.org/AnarchyPlanet/anarchyplanet-site)
|
|
in your browser again and click the green pull request button next to the
|
|
branch label.
|
|
* Select the branch you made, and open the pull request.
|
|
|
|
## Dependencies
|
|
|
|
We use [lowdown](https://kristaps.bsd.lv/lowdown/) for markdown
|
|
conversion. See its documentation:
|
|
|
|
* [overview](https://kristaps.bsd.lv/lowdown/)
|
|
* [lowdown(1)](https://kristaps.bsd.lv/lowdown/lowdown.1.html)
|
|
* [lowdown(5)](https://kristaps.bsd.lv/lowdown/lowdown.5.html) which
|
|
describes the lanuage syntax
|
|
|
|
The rest of the heavy lifting is done by a modified version of
|
|
[ssg](https://www.romanzolotarev.com/ssg.html) which is included
|
|
in this source code. ssg requires a POSIX /bin/sh, and awk.
|
|
|
|
## Deployment
|
|
|
|
Configure a webserver to serve static content (HTML, CSS, etc) from a
|
|
directory. You will define that directory as `DST` in the next step.
|
|
|
|
Clone this repository. Copy config.sample.mk to config.mk and edit it:
|
|
|
|
cp config.sample.mk config.mk
|
|
micro config.mk
|
|
|
|
Run make:
|
|
|
|
make
|
|
|
|
## TODOs
|
|
|
|
* [ ] TODO discuss and decide on sections
|
|
- notnull's proposals for the sections are:
|
|
* home
|
|
* projects (not services)
|
|
* webring (instead of 'others')
|
|
* contact (probably just a mailto: link)
|
|
* [ ] write copy for sections
|
|
- What rocinante has done on
|
|
[anarchist news](https://anarchistnews.org/content/anarchy-planet)
|
|
is already pretty great. Maybe these could be more verbose, but
|
|
maybe they are fine the way they are!
|
|
* [ ] add a favicon
|
|
* [ ] use an automatic toc generator
|
|
- and add to Makefile (make toc)
|
|
- see https://github.com/ekalinin/github-markdown-toc
|