From 9f0ec9166069b01506aac1e509e8fc16049c222f Mon Sep 17 00:00:00 2001 From: Syndamia Date: Sun, 7 May 2023 14:40:25 +0300 Subject: [README] Improved READMEs --- README.md | 64 ++++++++++++++++++++++++++++----------------------------------- 1 file changed, 28 insertions(+), 36 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index c12a347..0d2da8a 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,30 @@ # syndamiadotcom -Repository for my website. - -The pages of the website are (mostly) written in Markdown. Using [ssg](https://www.romanzolotarev.com/ssg.html) and [lowdown](https://kristaps.bsd.lv/lowdown/) they are generated into a **static** website. - -## Contents of this repository - -The `src` folder contains all of the website files, i.e. the pages, fonts, styles, images, etc. - -`install-ssg6-lowdown.sh` is a shell script that installs both ssg and lowdown. - -`generate.sh` is a shell script that automatically generates the website into a folder named "website". - -## About index.md files - -In a lot of folder, the `index.md` files are just hard links of other files! For example, `src/about/index.md` is a hard link to `src/about.html`. Why? Because this way, web links are a lot shorter: -``` -Old style link -> New style link - -syndamia.com/about.html -> syndamia.com/about -syndamia.com/tutorials/how-to-use-jira/introduction.html -> syndamia.com/tutorials/how-to-use-jira/ -``` -Of course, the old style links are still available, but the website itself won't be using them during navigation. - -### List of hard links - -In all **multi-page** articles (be it blog article or tutorial or etc.), `introduction.md` is the first page and `index.md` is a hard link to it. Single page articles are just titled `index.md` (it's not a hard link). - -|File at|Hard links to| -|---|---| -|`about/index.md`|`about.md`| -|`blog/index.md`|`blog.md`| -|`contact/index.md`|`contact.md`| -|`courses/index.md`|`courses.md`| -|`tutorials/index.md`|`tutorials.md`| - -*All links are relative to the src folder!* +Repository for my website. +Pages are written in Markdown, converted to HTML with [ssg](https://www.romanzolotarev.com/ssg.html) and [lowdown](https://kristaps.bsd.lv/lowdown/), and edited with AWK scripts. +Currently, all content is static. + +For more information on how it works, refer to [S.S. Law](https://syndamia.gitlab.io/ss-law/). + +## Layout and personal setup + +- `.hooks`: Scripts which are executed before git commit. + + `pre-commit.sh`: Most (blog, tutorial, ...) pages are accessed without the ending `.html`, which is done by moving the contents of `page.html` to `page/index.html`. + I would still like for certain pages to be accessible also with `page.html`, so I create a hardlink from one to the other. + However, git (when pulling) removes the appropriate hardlink and the files aren't "synced", this script brings back those hardlinks. +- `awk-edits`: After HTML generation of pages, AWK scripts do modifications. + For more information, read `awk-edits/README.md`. +- `src`: All website content +- `generate.sh`: Generates the whole website. + + You can give it arguments: + + With no argument, the website is created in a "production" way. + + With the `dev` parameter (`./generate.sh dev`), you'll get duration information for different stuff. + + With the `devs` argument, you'll get duration information, but AWK scripts will be ran individually, rather than being combined (useful for individual performance evaluation; name comes from dev + separated) + + There are some variables which handle how the script works: + + `REPO_FOLDER`: specifies where the repository is, useful if you want to run the script outside of the repo. + awk-edits and src folders are always relative to the repo folder. + + `GEN_FOLDER`: folder in which to put the final generated webpages + + `GEN_TINY_FOLDER`: folder in which to put the webpages, that have removed features for better accessibility + + `AWK_FILE`: where to put the temporary AWK script, which is created by combining all awk-edits scripts into one. + Obviously doesn't do anything with `devs` parameter. +- `install-ssg-lowdown.sh`: Installs ssg and lowdown on the current system. -- cgit v1.3.1-23-gd82d