From c0efeb2c257118db73174b9a799eddb520111c4d Mon Sep 17 00:00:00 2001 From: southerntofu Date: Mon, 30 Mar 2020 14:33:07 +0200 Subject: [PATCH] Update README --- README.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2912bef..876f288 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,111 @@ # dnsmanager-website -Prototype for a dnsmanager homepage +This repository contains a prototype for a [dnsmanager](https://github.com/KaneRoot/dnsmanager) homepage. Below, you will find instructions on how to use it and how to contribute to it. + +On a high-level, this website is made for [Zola](https://getzola.org) using the water.css stylesheet to decorate the semantic HTML on all pages. Currently this website does: + +- static pages +- blog articles +- internationalization (i18n) with support for localized dates + +# Setup + +If you want to contribute to this website, you first need to setup the [Zola](https://getzola.org) static site generator. You can either download a pre-compiled package, or compile the program from source using a [Rust](https://rust-lang.org) compiler. + +## Package setup + +For GNU/Linux users, there's a [snap](https://snapcraft.io/) package available (no Flatpack yet): + +``` +$ snap install --edge zola +``` + +On Mac, you can install zola using [Homebrew](https://brew.sh): + +``` +$ brew install zola +``` + +Alternatively, you can install a precompiled binary from the [Github releases](https://github.com/getzola/zola/releases): + +``` +$ wget https://github.com/getzola/zola/releases/download/v0.10.1/zola-v0.10.1-x86_64-unknown-linux-gnu.tar.gz +$ tar xf zola*.gz && rm zola*.gz +$ sudo cp zola /bin/ && rm ./zola +``` + +## Compile from source + +If you don't have rustc (the official Rust compiler) and cargo (the related package manager) setup, you can either install them through your distribution, or get the latest version directly from the Rust project using rustup. If you're using Nix or [GNU Guix](https://guix.gnu.org) for package management, you can also use those to setup cargo and rustc. + +If you're running Debian buster or later, you can simply do: + +``` +$ sudo apt install cargo rustc +``` + +If your distribution does not have a package for Rust, you can download [rustup](https://www.rust-lang.org/tools/install) and use it to setup a stable compiler. + +Once Rust is setup, we can download Zola's source and compile it. Make sure you have git installed (`sudo apt install git`) before you proceed: + +``` +$ git clone https://github.com/getzola/zola +$ git checkout v0.10.1 +$ cargo install --path=. +``` + +The last command (`cargo install`) not only compiles the project, but copies the generated binary to ~/.cargo/bin, which should already be in your `$PATH` after setting up Rust. You can check that zola is correctly setup by running it with the --version argument: + +``` +$ zola --version +zola 0.10.1 +``` + +If you have an error message such as `bash: zola: command not found`, it is neither a problem with the Zola project or this website. It means the cargo bin directory is not in your $PATH for executable programs. A few things you can try: + +- logging out then logging back in, if you've just setup rust, could apply changes to your $PATH +- appending `export PATH="$HOME/.cargo/bin:$PATH"` to your ~/.profile + +If you still fail at running zola, you should read your distro's documentation or ask a friend. + +## Compiling the site + +Now that zola is up and running, we can use it to build our website. When building a site, zola needs to know about its final address in order to generate links. + +``` +$ git clone https://tildegit.org/southerntofu/dnsmanager-website +$ cd dnsmanager-website +$ zola build +``` + +zola will then place all the generated files in the public/ folder. Note that zola needs to know about its base URL in order to generate links. By default, the base_url is defined in config.toml for the website's current address. You can pass another base URL as an argument to zola using the -u flag, and a different output folder using the -o flag: + +``` +$ zola build -u "http://localhost:1337" -o public_local/ +$ zola build -u "http://acab13122131baca.onion" -o public_onion/ +Building site... +-> Creating 7 pages (3 orphan), 5 sections, and processing 0 images +Done in 407ms. +``` + +## Live reload + +When updating the website content and stylesheets, you can run zola serve to setup a local web server with a preview of your changes: + +``` +Building site... +-> Creating 7 pages (3 orphan), 5 sections, and processing 0 images +Done in 730ms. + +Web server is available at http://127.0.0.1:1111 + +Listening for changes in /home/user/Desktop/Sites/dnsmanager/{content, config.toml, static, templates, themes, sass} +Press Ctrl+C to stop +``` + +You can then access the website at the address zola will output, usually [127.0.0.1:1111](http://127.0.0.1:1111). + +Note that this live reload feature does not entirely play well with the macro system at the moment, so if you see some changes in your work are not reflected on the preview, don't hesitate to kill zola using `Ctrl-c` and then start it again. # Blog @@ -49,6 +154,15 @@ title = "New post" As explained in the [introduction](@/introduction/index.md), we should abolish the government. ``` +## Transitioning to a new year + +If a new year is starting, you may want to create a new folder for the year and copy the placeholder section files from the past year into the new folder (one file per available language): + +``` +$ mkdir content/blog/2021 +$ cp content/blog/2020/_index.*.md content/blog/2021 +``` + # Translations ## Add a new language @@ -126,6 +240,7 @@ If something is missing for you, please open an issue. - [ ] links to navigate between languages - [ ] other - [x] ASCII banner does not overflow - - [ ] write setup/configuration guide + - [x] write setup/configuration guide - [ ] reference water.css semantic styling - [x] RSS links +