{"id":19876398,"url":"https://github.com/foo-dogsquared/website","last_synced_at":"2025-03-01T01:42:09.559Z","repository":{"id":65254661,"uuid":"310655922","full_name":"foo-dogsquared/website","owner":"foo-dogsquared","description":"My Hugo-built website.","archived":false,"fork":false,"pushed_at":"2025-02-23T01:21:45.000Z","size":27868,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-23T02:24:33.840Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://foodogsquared.one/","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/foo-dogsquared.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-06T16:56:39.000Z","updated_at":"2025-02-23T01:21:49.000Z","dependencies_parsed_at":"2023-10-15T21:58:39.287Z","dependency_job_id":"0c2b861e-d3f3-458b-9633-c16e51c2870b","html_url":"https://github.com/foo-dogsquared/website","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foo-dogsquared%2Fwebsite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foo-dogsquared%2Fwebsite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foo-dogsquared%2Fwebsite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foo-dogsquared%2Fwebsite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foo-dogsquared","download_url":"https://codeload.github.com/foo-dogsquared/website/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241304296,"owners_count":19941101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T16:32:55.759Z","updated_at":"2025-03-01T01:42:09.543Z","avatar_url":"https://github.com/foo-dogsquared.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"= blog\n:toc:\n\nMy website featuring a fairly customized version of https://github.com/foo-dogsquared/hugo-theme-more-contentful/[my More Contentful Hugo theme].\n\n\n\n\n== Setting things up\n\nYou need link:https://nixos.org[Nix package manager] installed to easily replicate the development shell for this project.\nOtherwise, you might have to manually install the following components:\n\n- link:https://gohugo.io/[Hugo] as it is the tool used to generate this website.\n- https://go.dev/[Go runtime] as the Hugo project uses link:https://gohugo.io/hugo-modules/[Hugo modules].\n- Git not only because it is the VCS this project uses but also because it is used for Hugo modules.\n- link:https://www.ruby-lang.org/en/[Ruby] as this site uses Asciidoctor and custom Asciidoctor extensions.\n- link:https://git.sr.ht/~sircmpwn/openring[openring] for generating a webring which is used on the site homepage.\n- link:https://imagemagick.org/[ImageMagick] for processing the image files.\n\nWith the things installed, you can just clone the Git repo of this project, run `rake serve`, and voila!\nYou're now a content creator!\n\nMost of the usual tasks done with this project should be handled by this project already which is listed in its link:./Rakefile[Rakefile].\nYou can view the file for more details but for the sake of completion, here are the following tasks.\n\n- Building the website with `rake serve`.\n- Updating the Hugo modules with `rake update`.\n- Easily creating a live server with `rake serve`.\n\n\n\n\n== Workflow\n\nThe workflow should be pretty easy to get started.\nHere are the non-exhaustive writing guidelines for this project.\n\n- You can edit any text with the text editor of your choice.\n- The content uses Asciidoc markup with Asciidoctor toolchain.\n- The content also uses custom Asciidoctor extensions, all of which is cited on the link:Gemfile[`Gemfile`].\n\nThe posts from this website have a certain folder structure to follow.\nAll of them should have a dedicated folder named `$PUBLISH_DATE_IN_ISO_FORMAT-$POST_TITLE_IN_KEBAB_CASE`.\nFor 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.\nYou can easily create one with `hugo new posts/$FOLDER_NAME/index.adoc`.\n\n\n=== Content branches\n\nThere is another thing that this project uses which is set of dedicated branches for containing code for certain posts.\nFor example, the content branch `content/posts/2023-03-31-how-to-pick-your-nose` contains code walkthroughs to be used on the same content from the content directory.\n\nThis setup allows us to easily write code walkthroughs.\nEach of those branch are basically dedicated branches for content which can be retrieved inside of the Asciidoctor document.\n\nAnother thing to set up is to create a link:https://git-scm.com/docs/git-worktree[Git worktree].\nMostly, it is expected to be in a directory inside of the project.\n\n[source, shell]\n----\ngit worktree add ./code-workspace\n----\n\nThe above directory is typically used for the `content/*` branches.\n\n\n=== Getting used to with Asciidoctor\n\nThis Hugo project uses Asciidoc markup with Asciidoctor due to more markup features found in it compared to Markdown.\nNot to mention, it easily allows extending the markup with its API which this project also makes use of.\n\nSpeaking of extending Asciidoctor, we use our own set of custom Asciidoctor extensions https://github.com/foo-dogsquared/asciidoctor-foodogsquared-extensions[deployed with RubyGems].\n\nNOTE: If you have Nix, this is already handled for you so feel free to skip the following section.\n\n\n=== Asciidoctor custom include processors\n\nThis website uses its own set of Asciidoctor extension as depicted from the above section.\nBut there are more than shorthand macros for certain types of link.\n\nThe most useful (arguably) types of extension found here are the include processors.\n\n- An include processor for retrieving Git objects with `git:`.\nThis might not sound great but it allows me to create dedicated branches for certain content.\nPlus, it easily creates patches which is nice to create code walkthroughs.\n\n- An include processor for SWHIDs but only with content blobs (i.e., `swh:cnt:`).\nVery useful for referring to archived codebases.\n\n\n=== General content taxonomy\n\nWhile this is mostly referring to link:http://gohugo.io/content-management/taxonomies/[Hugo taxonomies], this is generally applicable to similar features found in other site generators.\nThe way how I describe the relationship of the content for the end user is pretty simple as it only contains two taxonomy: tags and series.\n\n- Each content may have multiple tags attached to them.\nThese tags are basically referring to a field of various scopes.\nIt can go from a very broad field (e.g., Programming) to a specific one (e.g., Web development).\nI recommend to be as specific as possible with the tags.\n\n- Each content can be a part of a series.\nA content can only be one series at any given time.\nA series is typically encompassing in its scope and should have an introductory post as to what it is and its aims.\n\n\n=== Deployment\n\nThis project uses Netlify to deploy the website.\nHowever, this uses GitHub Actions to build the website since Netlify is too limited for our this project needs.\n\nThe building step for this website should be the same as the (encouraged) workflow with Nix development shells.\nHence, it should be run with `make build` and deploy the website with `public/` folder.\n\n\n\n\n== Project development guidelines\n\nThis project is developed with some habits.\nThe following non-definitive list show those habits.\n\n- This project uses link:https://github.com/sagittaros/ruby-nix[a custom Ruby bundler for Nix environments].\nIt only needs `gemset.nix` but it is generated from `Gemfile.lock`.\nTo generate them, you can run the following command:\n+\n--\n[source, shell]\n----\nnix run github:sagittaros/bundix -- -l\n----\n\nTake note you need to do this every time you change the Ruby environment.\n--\n\n- It needs `content/*` branches to be deployed with the site.\nThis is because several posts uses a link:./gems/lib/asciidoctor/git-blob-include-processor[an Asciidoctor extension to include content from other Git revisions].\nThis means you have to fetch them into your local Git repo.\n+\n--\n[source, shell]\n----\ngit fetch origin +refs/heads/content/*:refs/heads/content/*\n----\n\nYou can easily a dedicated content branch with link:./bin/switch-content-orphan-branch.rb[./bin/switch-content-orphan-branch.rb].\n--\n\n- For content drafts, it is recommended to create a dedicated branch for it.\nThis branch needs to have a prefix of `drafts/` with the filename relative to the content directory (e.g., `drafts/posts/2023-03-26-how-to-pick-your-nose`).\nThis step is already automated with link:./bin/create-draft-branch.rb[`./bin/create-draft-branch.rb`].\n\n- Consequently with previous guideline, it is recommend to commit daily and commit often with the drafts.\nOnce it is done, a rebase should be done with a squashed commit publishing the content.\n\n- The link:./assets/svg/avatars[avatar images] are processed with ImageMagick.\nFurthermore, they should be optimized.\nThe simple avatar designs such as link:./assets/svg/avatars/ezran/default.svg[./assets/svg/avatars/ezran/default.svg] can be reduced and optimized up to 90% of its quality.\nThough, this depends on the encoding of the format (e.g., WebP, AVIF).\nThe following command should show how it is done.\n+\n--\n[source, shell]\n----\nmagick convert $AVATAR -quality 30 $AVATAR_OUTPUT\n----\n--\n\n\n\n\n\n== Copyright\n\nThe template used for this site is licensed under MIT license which you can link:./LICENSE[view the file in full detail].\nThe link:./content/[content that is hosted in here] are my intellectual property.\nHowever, code samples from the content are dual-licensed under MIT and AGPLv3.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoo-dogsquared%2Fwebsite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoo-dogsquared%2Fwebsite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoo-dogsquared%2Fwebsite/lists"}