From 82b3e6dff8ee44796abe4b33d63de71babf9df5b Mon Sep 17 00:00:00 2001 From: Gabriel Arazas Date: Sat, 25 Mar 2023 13:40:05 +0800 Subject: [PATCH] Update README --- README.adoc | 137 +++++++++++++++++++++------------------------------- 1 file changed, 55 insertions(+), 82 deletions(-) diff --git a/README.adoc b/README.adoc index 7ce2f39..c682555 100644 --- a/README.adoc +++ b/README.adoc @@ -1,104 +1,77 @@ = blog +:toc: -My blog featuring a fairly customized version of https://github.com/foo-dogsquared/hugo-theme-more-contentful/[my More Contentful Hugo theme]. +My website featuring a fairly customized version of https://github.com/foo-dogsquared/hugo-theme-more-contentful/[my More Contentful Hugo theme]. -== Getting started +== Setting things up -Though, it's obvious but then again, you may not remember how to do well in a year. +You need link:https://nixos.org[Nix package manager] installed to easily replicate the development shell for this project. +Otherwise, you might have to manually install the following components: +- link:https://gohugo.io/[Hugo] as it is the tool used to generate this website. +- https://go.dev/[Go runtime] as the Hugo project uses link:https://gohugo.io/hugo-modules/[Hugo modules]. +- Git not only because it is the VCS this project uses but also because it is used for Hugo modules. +- link:https://asciidoctor.org/[Asciidoctor] as it is the content markup used for the Hugo site. +- link:https://www.ruby-lang.org/en/[Ruby] as this site uses custom Asciidoctor extensions. +- link:https://git.sr.ht/~sircmpwn/openring[openring] for generating a webring which is used on the site homepage. -=== Prerequisites +With the things installed, you can just clone the Git repo of this project, run `make serve`, and voila! +You're now a content creator! -* Git -* Hugo -* https://golang.org/[Go] runtime -* https://asciidoctor.org/[Asciidoctor] -* https://stedolan.github.io/jq/[jq] -* https://git.sr.ht/~sircmpwn/openring/[openring] (you can easily compile one yourself with the Go toolchain) -* https://www.gnu.org/software/make/[GNU Make] is optional but it'll make your life easier. -* https://nixos.org/[Nix] is also optional but it'll make your life into an enlightened functional package management heaven. +Most of the usual tasks done with this project should be handled by this project already which is listed in its link:Makefile[Makefile]. +You can view the file for more details but for the sake of completion, here are the following tasks. - -=== Setting up - -[source, shell] ----- -git clone $GIT_REPO -hugo mod get -u -hugo serve ----- - -Or you could simply get a server running with `make serve` and bada-bing, bada-boom! -You're now a "content creator"! - -The theme is a modified version of a https://github.com/foo-dogsquared/hugo-theme-more-contentful[modified version of a theme] so that's pretty cool. - -To create a post, simply make with `hugo new --kind post $PATH_REL_TO_CONTENT_DIR` and you're on your merry way. - - -=== Setting up with Nix - -If you have Nix installed, it is even easier by creating a https://nix.dev/tutorials/ad-hoc-developer-environments.html[local development environment] for this project. -And it already has one in link:shell.nix[`shell.nix`]. - -Just run `nix-shell --pure shell.nix` and you're set. -An additional benefit with this setup is you don't have to manually compile https://git.sr.ht/~sircmpwn/openring/[openring] since the config already sets it for you. - -Even better, you can set up an automatic shell environment with https://direnv.net/[direnv]. -To use it, just add `.envrc`! - -[source, bash] ----- -echo "use nix" > .envrc && direnv allow ----- - - -=== Deploying your blog - -As of 2020-11-14, the blog is deployed into GitHub Pages with http://travis-ci.com/[Travis CI] for automation. -Feel free to copy the link:.travis.yml[`.travis.yml`] for an idea. - -Nonetheless, it is easy to migrate between hosts since Hugo is fast and simple. -All you need to do is to run `make build`. -Then, upload the build artefacts into your host provider of choice. +- Building the website with `make serve`. +- Updating the Hugo modules with `make update`. +- Easily creating a live server with `make serve`. -== Project structure +== Workflow -[source, tree] ----- -blog -├── archetypes/ -├── assets/ -├── bin/ -├── content/ -├── data/ -├── layouts/ -├── public/ -├── resources/ -├── static/ -├── config.toml -├── go.mod -├── go.sum -├── Makefile -├── README.adoc -└── shell.nix ----- +The workflow should be pretty easy to get started. +Here are the non-exhaustive guidelines for this project. -Among all of the files laid above, here are the points of interest you're most likely to interact (aside from the content folder). +- You can edit any text with the text editor of your choice. +- The content uses Asciidoc markup with Asciidoctor toolchain. +- The content also uses custom Asciidoctor extensions, all of which is cited on the link:Gemfile[`Gemfile`]. +- There is a Ruby gem for our own Asciidoctor extensions which is living at link:./gems/[`./gems/`]. -* The link:./bin[`./bin`] directory contains custom scripts related for this project. -An example of which is a script (i.e., link:./bin/openring-create[`./bin/openring-create`]) that uses https://git.sr.ht/~sircmpwn/openring/[openring] to create a webring from my link:./data/blogs.json[public list of blogs I follow]. +The posts from this website have a certain folder structure to follow. +All of them should have a dedicated folder named `$PUBLISH_DATE_IN_ISO_FORMAT-$POST_TITLE_IN_KEBAB_CASE`. +For example, if you have a post titled "How to pick your nose" published on March 31 of 2023, you have to store it in a folder `2023-03-31-how-to-pick-your-nose` in the content Hugo folder. +You can easily create one with `hugo new posts/$FOLDER_NAME/index.adoc`. -* link:./shell.nix[`./shell.nix`] is used for quickly creating a local project environment. -It can be only used when Nix is installed. -* The link:./data/[data folder] contains some of the https://github.com/foo-dogsquared/hugo-theme-more-contentful/[theme] configuration as well as relevant data for my customizations. +=== Getting used to with Asciidoctor -* The link:./layouts/[layout folder] contains theme overrides as well as additional components for custom content types (e.g., making appropriate templates for my gallery section, modifying the post section to be more readable). +This Hugo project uses Asciidoc markup with Asciidoctor due to more markup features found in it compared to Markdown. +Not to mention, it easily allows extending the markup with its API which this project also makes use of. +To get it working, you need to install the Ruby gem found in link:./gems/[`./gems/`]. +NOTE: If you have Nix, this is already handled for you so feel free to skip the following section. + +- Build the gem in the gems directory (i.e., `cd gems && gem build asciidoctor-foodogsquared-extensions.gemspec`) +- Install the gem (i.e., `gem install ./asciidoctor-foodogsquared-extensions-1.0.0.gem`). +- With the gem installed, you can make use of the Asciidoctor extensions from it. + +Here's a couple of macros with this extension. + +- An inline macro for easily linking manpages in a variety of websites (i.e., `man:crontab[5]`, `man:systemd.unit[5]`). +- An inline macro for GitHub (i.e., `github:foo-dogsquared/nixos-config[]`, `github:NixOS/nixpkgs[]`) and GitLab (i.e., `gitlab:gitlab-org/gitlab`). +- Yet another inline macro for linking link:https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html[SWHIDs] (i.e., `swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2[]`, `swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505[]`). + +For more details, you can see link:./gems/lib/asciidoctor[`./gems/lib/asciidoctor`] for more details. + + +=== Deployment + +This project uses Netlify to deploy the website. +However, this uses GitHub Actions to build the website since Netlify is too limited for our this project needs. + +The building step for this website should be the same as the (encouraged) workflow with Nix development shells. +Hence, it should be run with `make build` and deploy the website with `public/` folder.