foodogsquared/website
1
0
Fork 0
mirror of https://github.com/foo-dogsquared/website.git synced 2025-02-07 09:19:00 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Gabriel Arazas 2023-03-25 13:40:05 +08:00
parent f6dc3b07f4
commit 82b3e6dff8
No known key found for this signature in database
GPG Key ID: ADE0C41DAB221FCC
1 changed files with 55 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
README.adoc
View File

@ -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.