diff --git a/README.md b/README.md index 81199ff..127ca6f 100755 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This README is the central technical guide for the repository: start here for ar The application has three boundaries: 1. **Site source (this repository):** Org/Markdown content, Emacs Lisp publishing code, CSS, JavaScript, images, and build tooling. -2. **Static output (`output/`):** generated HTML, copied assets, and `search-index.json`. This is the deployable website, not the source of truth. +2. **Static output (**`output/`**):** generated HTML, copied assets, and `search-index.json`. This is the deployable website, not the source of truth. 3. **Runtime services (outside this repository):** the authoring service and the same-origin APIs used by interactive pages. The static site remains readable without them, but the relevant dynamic features will not work. ```mermaid @@ -25,26 +25,26 @@ flowchart LR ## Repository map -| Path | Purpose | Source or generated? | -| --- | --- | --- | -| `index.org` | Home page source | Source | -| `blogs/` | Dated personal writing, grouped by year/month | Source, except generated list pages | -| `posts/` | Longer-lived posts; `posts/career/` has its own index | Source, except generated list pages | -| `home/` | Utility and dashboard-style pages | Source, except `categories.org` | -| `play/` | Interactive and experimental pages | Source | -| `rl/` | Browser-local Resource Loader SPA | Source | -| `lima/` | Org or Markdown pages with special attachment handling | Source, except `lima-list.org` | -| `assets/` | Browser code, styles, fonts, images, and content manifests | Mostly source; some manifests/scripts are generated externally | -| `lisp/` | Modular Emacs Lisp publishing system | Source | -| `lisp/tests/` | ERT tests for the publishing logic | Source | -| `tags/` | Per-tag Org pages created during a build | Generated | -| `recently-updated.org` | Recent-content list created during a build | Generated | -| `sitemap.org` and `*-list.org` | Sitemap/list sources created by `org-publish` | Generated | -| `output/` | Complete publish output | Generated | -| `.org-timestamps/` | Incremental publish cache | Generated | -| `.packages/` | Repository-local Emacs package directory | Generated/cache | -| `build-logs/` | Gitea build monitoring script, cache, and logs | Mixed; script is source, logs/cache are runtime data | -| `docs/` | Historical/design notes for individual features | Supplemental; this README is the central engineering guide | +| Path | Purpose | Source or generated? | +|----------------------------|------------------------------------------------------------|----------------------------------------------------------------| +| `index.org` | Home page source | Source | +| `blogs/` | Dated personal writing, grouped by year/month | Source, except generated list pages | +| `posts/` | Longer-lived posts; `posts/career/` has its own index | Source, except generated list pages | +| `home/` | Utility and dashboard-style pages | Source, except `categories.org` | +| `play/` | Interactive and experimental pages | Source | +| `rl/` | Browser-local Resource Loader SPA | Source | +| `lima/` | Org or Markdown pages with special attachment handling | Source, except `lima-list.org` | +| `assets/` | Browser code, styles, fonts, images, and content manifests | Mostly source; some manifests/scripts are generated externally | +| `lisp/` | Modular Emacs Lisp publishing system | Source | +| `lisp/tests/` | ERT tests for the publishing logic | Source | +| `tags/` | Per-tag Org pages created during a build | Generated | +| `recently-updated.org` | Recent-content list created during a build | Generated | +| `sitemap.org` and `*-list.org` | Sitemap/list sources created by `org-publish` | Generated | +| `output/` | Complete publish output | Generated | +| `.org-timestamps/` | Incremental publish cache | Generated | +| `.packages/` | Repository-local Emacs package directory | Generated/cache | +| `build-logs/` | Gitea build monitoring script, cache, and logs | Mixed; script is source, logs/cache are runtime data | +| `docs/` | Historical/design notes for individual features | Supplemental; this README is the central engineering guide | ## Build architecture @@ -67,19 +67,19 @@ flowchart TD ### Build modules -| Module | Responsibility | -| --- | --- | -| `build-core.el` | Logging, timing, local package bootstrap, and base Org configuration | -| `build-assets.el` | Shared CSS/JS `` manifest, cache-busted asset URLs, and asset synchronization | -| `build-html.el` | Custom HTML backend, page shell, Mermaid export, macros, body classes, tags, and comments | -| `build-projects.el` | `org-publish-project-alist` for the main site, posts, blogs, career, tags, Lima, categories, and assets | -| `build-runner.el` | Cache integrity, generated inputs, publishing, and build metrics | -| `build-lima.el` | Lima Org/Markdown conversion and neighboring attachment copying | -| `build-comments.el` | Comment opt-in detection, comment HTML injection, and comment-page manifest generation | -| `sitemaps.el` | Main Mermaid sitemap and specialized blog/post/career/category lists | -| `tags.el` | Tag discovery, generated tag pages, and tag markup in exported HTML | -| `recently-updated.el` | Recent page list generation using `#+DATE` with mtime fallback | -| `sidenotes.el` | Sidenote suppression rules for special page layouts | +| Module | Responsibility | +|---------------------|-------------------------------------------------------------------------------------------------------| +| `build-core.el` | Logging, timing, local package bootstrap, and base Org configuration | +| `build-assets.el` | Shared CSS/JS `` manifest, cache-busted asset URLs, and asset synchronization | +| `build-html.el` | Custom HTML backend, page shell, Mermaid export, macros, body classes, tags, and comments | +| `build-projects.el` | `org-publish-project-alist` for the main site, posts, blogs, career, tags, Lima, categories, and assets | +| `build-runner.el` | Cache integrity, generated inputs, publishing, and build metrics | +| `build-lima.el` | Lima Org/Markdown conversion and neighboring attachment copying | +| `build-comments.el` | Comment opt-in detection, comment HTML injection, and comment-page manifest generation | +| `sitemaps.el` | Main Mermaid sitemap and specialized blog/post/career/category lists | +| `tags.el` | Tag discovery, generated tag pages, and tag markup in exported HTML | +| `recently-updated.el` | Recent page list generation using `#+DATE` with mtime fallback | +| `sidenotes.el` | Sidenote suppression rules for special page layouts | The main `org-main` project recursively publishes every Org file, while narrower projects provide specialized sitemap behavior and options. That overlap is intentional: Org's timestamp cache prevents unnecessary repeated work in normal incremental builds. @@ -139,25 +139,25 @@ Then open `http://127.0.0.1:8000`. Dynamic `/api/...` features require the exter ### Make targets -| Command | Effect | -| --- | --- | -| `make build` | Run the Emacs publishing pipeline | -| `make search` | Create/update `output/search-index.json`, creating `.venv` when needed | -| `make` | Set machine-specific permissions, remove `output/`, build, index search, and remove `.venv` | -| `make clean-output` | Delete the configured output directory | -| `make test-elisp` | Run the Emacs Lisp ERT suite | -| `make test` | Run tests in the sibling authoring-service repository | -| `make norm` | Move Emacs backup files into `backups/` | -| `make help` | List supported targets | +| Command | Effect | +|-------------------|-----------------------------------------------------------------------------------------| +| `make build` | Run the Emacs publishing pipeline | +| `make search` | Create/update `output/search-index.json`, creating `.venv` when needed | +| `make` | Set machine-specific permissions, remove `output/`, build, index search, and remove `.venv` | +| `make clean-output` | Delete the configured output directory | +| `make test-elisp` | Run the Emacs Lisp ERT suite | +| `make test` | Run tests in the sibling authoring-service repository | +| `make norm` | Move Emacs backup files into `backups/` | +| `make help` | List supported targets | ### Build environment variables -| Variable | Meaning | -| --- | --- | +| Variable | Meaning | +|-----------------------|--------------------------------------------------------------------------| | `SITE_OUTPUT_DIR=/path` | Publish somewhere other than `output/`; the Python indexer respects it too | -| `SITE_FORCE=1` | Republish every file instead of using Org timestamps | -| `SITE_DRY=1` | Generate/prepare inputs but skip `org-publish-all` | -| `SITE_CLEAN=1` | Delete output and `.org-timestamps/`, then force a full publish | +| `SITE_FORCE=1` | Republish every file instead of using Org timestamps | +| `SITE_DRY=1` | Generate/prepare inputs but skip `org-publish-all` | +| `SITE_CLEAN=1` | Delete output and `.org-timestamps/`, then force a full publish | The build checks that assets and an entry page exist in the output. If the output is missing or incomplete while timestamps remain, it clears the timestamp cache and forces a full publish to avoid a falsely successful incremental build. @@ -269,12 +269,12 @@ Third-party browser dependencies are vendored: Lunr, Mermaid, BiggerPicture, and The published HTML is static, but some browser modules rely on same-origin APIs: -| Feature | Browser module | Runtime endpoint | -| --- | --- | --- | -| Comments and replies | `features/comments.js` | `GET /api/comments/:slug`, `POST /api/comments` | -| Notes board | `pages/notes.js` | `/api/notes` | -| Wird tracker | `pages/wird-tracker.js` | `/api/wird`, `/api/wird/motalah`, `/api/calibre/books` | -| Competency board | `pages/competency-status-board.js` | `/api/competencies/items...` | +| Feature | Browser module | Runtime endpoint | +|----------------------|----------------------------------|--------------------------------------------------| +| Comments and replies | `features/comments.js` | `GET /api/comments/:slug`, `POST /api/comments` | +| Notes board | `pages/notes.js` | `/api/notes` | +| Wird tracker | `pages/wird-tracker.js` | `/api/wird`, `/api/wird/motalah`, `/api/calibre/books` | +| Competency board | `pages/competency-status-board.js` | `/api/competencies/items...` | These APIs are not implemented here. Production routing must serve `output/` and proxy `/api/` to the appropriate backend. When changing an endpoint contract, coordinate the static client and its external service. @@ -401,4 +401,4 @@ Static file serving does not provide `/api/...`. Run/proxy the relevant external ### The full `make` command fails outside the production host -`make` runs a hard-coded permission helper with `sudo`. Use `make build` followed by `make search`, or the portable commands above, on another machine. +`make` runs a hard-coded permission helper with `sudo`. Use `make build` followed by `make search`, or the portable commands above, on another machine. \ No newline at end of file diff --git a/assets/content/resource-loader.json b/assets/content/resource-loader.json old mode 100644 new mode 100755 diff --git a/assets/scripts/pages/resource-loader-model.js b/assets/scripts/pages/resource-loader-model.js old mode 100644 new mode 100755 diff --git a/assets/scripts/pages/resource-loader.js b/assets/scripts/pages/resource-loader.js old mode 100644 new mode 100755 diff --git a/assets/scripts/vendor/pdf.min.js b/assets/scripts/vendor/pdf.min.js old mode 100644 new mode 100755 diff --git a/assets/scripts/vendor/pdf.worker.min.js b/assets/scripts/vendor/pdf.worker.min.js old mode 100644 new mode 100755 diff --git a/assets/scripts/vendor/pdfjs-LICENSE.txt b/assets/scripts/vendor/pdfjs-LICENSE.txt old mode 100644 new mode 100755 diff --git a/assets/styles/pages/resource-loader.css b/assets/styles/pages/resource-loader.css old mode 100644 new mode 100755 diff --git a/build-logs/gitea-build-monitor.log b/build-logs/gitea-build-monitor.log index 053fe46..2fe5295 100755 --- a/build-logs/gitea-build-monitor.log +++ b/build-logs/gitea-build-monitor.log @@ -919,3 +919,15 @@ at , /home/zaine/master-folder/org-platform/org_web/build-logs/gite 2026-08-19T15:04:24.8154673+01:00 [INFO] Running authoring server tests with /home/zaine/master-folder/org-platform/authoring-service/.venv/bin/python. 2026-08-19T15:04:24.9273258+01:00 [INFO] Authoring server tests passed: ran=0, failures=0, errors=0, skipped=0, exit=0 2026-08-19T15:04:25.2285917+01:00 [INFO] Sent authoring server test notification. +2026-08-19T15:36:49.7043124+01:00 [INFO] Prepared current build status for zaine/org_web: severity=Info, status=success +2026-08-19T15:36:49.7142398+01:00 [INFO] Fetching recent Gitea Actions runs for zaine/org_web. +2026-08-19T15:36:50.4956922+01:00 [INFO] Sent build status notification with 1 embed(s). +2026-08-19T15:36:50.5182780+01:00 [INFO] Running authoring server tests with /home/zaine/master-folder/org-platform/authoring-service/.venv/bin/python. +2026-08-19T15:36:50.6014547+01:00 [INFO] Authoring server tests passed: ran=0, failures=0, errors=0, skipped=0, exit=0 +2026-08-19T15:36:51.0192881+01:00 [INFO] Sent authoring server test notification. +2026-08-20T01:01:37.0488761+01:00 [INFO] Prepared current build status for zaine/org_web: severity=Info, status=success +2026-08-20T01:01:37.0565558+01:00 [INFO] Fetching recent Gitea Actions runs for zaine/org_web. +2026-08-20T01:01:37.9035365+01:00 [INFO] Sent build status notification with 1 embed(s). +2026-08-20T01:01:37.9236959+01:00 [INFO] Running authoring server tests with /home/zaine/master-folder/org-platform/authoring-service/.venv/bin/python. +2026-08-20T01:01:38.0020346+01:00 [INFO] Authoring server tests passed: ran=0, failures=0, errors=0, skipped=0, exit=0 +2026-08-20T01:01:38.3206364+01:00 [INFO] Sent authoring server test notification. diff --git a/home/#backlog.org# b/home/#backlog.org# deleted file mode 100755 index f97c5ad..0000000 --- a/home/#backlog.org# +++ /dev/null @@ -1,32 +0,0 @@ -#+TITLE: Backlog -#+OPTIONS: num:nil toc:nil -#+DATE: <2025-11-08 Sat 11:08> -#+filetags: :emacs:website: -#+COMMENTS: t -#+SLUG: backlog - -* TODO - - - -* DOING - - - -* DONE - -- Add a notes page <2025-12-18 Thu> -- Add a *move* function in the competencies board page for mobile <2025-12-18 Thu> -- Refactor the build script to extract functions into seperate files <2025-12-16 Tue> -- Add a WIP property in an org file. If the header contains the string "WIP" then create a list of all WIP items and add to it. Otherwise do nothing. -- Page for latest updated files. -- Give lima extra controls, and update the syntax file for her. -- Service for RDP -- Create the backlog page. -- Database permissions (roles, accounts and schemas) <2026-01-18 Sun> -- how pipelines work <2026-01-18 Sun> -- Use zero trust cloudflare instead of nginx auth <2026-04-01 Wed> - -* For another time - -- Instead of deleting the output directory each time the website is built, only delete the files that have been changed. diff --git a/home/.#backlog.org b/home/.#backlog.org deleted file mode 100755 index b42f7fd..0000000 --- a/home/.#backlog.org +++ /dev/null @@ -1 +0,0 @@ -zqayyum@MCSFVGYNC4.33968:1787127281 \ No newline at end of file diff --git a/home/backlog.org b/home/backlog.org index a7cbcab..f97c5ad 100755 --- a/home/backlog.org +++ b/home/backlog.org @@ -8,6 +8,7 @@ * TODO + * DOING @@ -25,8 +26,6 @@ - Database permissions (roles, accounts and schemas) <2026-01-18 Sun> - how pipelines work <2026-01-18 Sun> - Use zero trust cloudflare instead of nginx auth <2026-04-01 Wed> - -* Things to add to 2026: * For another time diff --git a/posts/career/solid-principles.org b/posts/career/solid-principles.org index 9c63c72..2d55c2c 100755 --- a/posts/career/solid-principles.org +++ b/posts/career/solid-principles.org @@ -5,17 +5,28 @@ #+COMMENTS: t #+SLUG: solid-principles -The SOLID principles are five design guidelines for writing maintainable, flexible, and scalable object-oriented code. Here's a quick summary: +The 5 SOLID principles are guidelines that makes the code more maintainable and scalable. They enhance a term known as loose coupling, which means that the components have minimal dependancies on one another. This is particularly useful as it allows for the code to be reusable, scalable, flexible, stable and maintainable. -1. Single Responsibility Principle (SRP): A class should have only one reason to change, meaning it should have a single responsibility or purpose. +- S - Single responsability Principle: The objective of this principle is that a class should only have one reason to change. In other words, every class should fulfill a single responsability. An example is a cashier, whose job is to scan goods, process payments and give the customers their goods. If the responsability of the cashier is also to meet with suppliers, then this violates SRP. This principle is useful as it allows us to have a clear seperation of concerns, thus allowing us to have more modular and understandable code. -2. Open/Closed Principle (OCP): Classes should be open for extension (e.g., adding new functionality) but closed for modification (no need to change existing code). +- O - Open Closed Principle: The objective of this principle is to allow for software entities (such as classes, functions and modules) to be open for extension but closed for modification. What this means is that you should be able to extend a class behaviour (maybe adding more functions) without modifying it. -3. Liskov Substitution Principle (LSP): Subclasses should be substitutable for their base classes without breaking the program's behavior. +- L - Liskov's Substitution Principle: This principle ensures that any class that is the child of a parent class (derived) should be usable in place of its parent without any unexpected behaviour. The famous example used to explain this is a rectangle and square. A rectangle has 4 sides, the height and width can be any value. A square is a rectangle with equal width and height, so we say that the properties of the rectangle class extends into the square class. The derived class does not affect the behaviour of the parent class, therefore does not violate the principle. -4. Interface Segregation Principle (ISP): Clients should not be forced to depend on interfaces they don't use, favoring specific, small interfaces over large, general ones. +- I - Interface Segregation Principle: This principle is different from the others in the sense that it applies to interfaces rather than classes. It states that you should not force any client to implement an interface which is irrelevant to them. What this means is that you should prefer having many client interfaces rather than a single general interface. For example, if a restaurant has vegetarian and non vegetarian items, the waiter should give the customer a menu card that's specific for vegetarian items. The menu should be different for different types of customers. -5. Dependency Inversion Principle (DIP): High-level modules should not depend on low-level modules; both should depend on abstractions (e.g., interfaces), and abstractions should not depend on details. +- D - Dependency Inversion Principle: This principle states that high level modules should not depend on low level modules, both should depend on abstractions. Furthermore, the abstractions should not depend on details. In other words, classes should rely on abstractions rather than concrete implementations. For example, in a software development team, developers depend on an abstract version control system like Git. They do not depend on the specific details about how it works internally. -These principles promote cleaner, more modular, and testable code. +** Why is SOLID principles needed? +- It makes code easier to maintain. This is thanks to each class having a clear responsability (SRP). +- Allows for scalability. This is thanks to the open closed principle, allowing for new features to be added without changing existing code. +- Allows for flexibility. This is thanks to the DIP, which allows developers to change components without disrupting the whole system. + +** The following may be cases where it may not be necessary to use the SOLID principles: + +- One off or short lived projects. This is because not all software needs long term maintenance. +- Performance critical applications. Enforcing SOLID here can result in performance bottlenecks. +- Small and self contained applications. If the system serves limited purpose, adhering strictly to the SOLID principles can lead to over engineering. + +The following article explains in detail exactly when to avoid the principles: [[https://www.baeldung.com/cs/solid-principles-avoid][When Using Solid Principles May Not Be Appropriate]] diff --git a/posts/posts-list.org b/posts/posts-list.org index acc4ccf..5f6a46e 100755 --- a/posts/posts-list.org +++ b/posts/posts-list.org @@ -4,7 +4,7 @@ See the categories: @@html:Categories@@ * Posts: -- [[file:career/career-list.org][Career List]] @@html:19-08-2026 15:31@@ +- [[file:career/career-list.org][Career List]] @@html:19-08-2026 15:36@@ - [[file:career/cross-site-scripting-xss.org][Cross-Site Scripting (XSS)]] @@html:01-06-2026 10:21@@ @@html:learning@@ @@html:notes@@ - [[file:career/ha-dr.org][High Availability, Disaster Recovery and Business Continuity]] @@html:11-03-2026 17:18@@ @@html:learning@@ @@html:notes@@ - [[file:career/javascript.org][Understands the Javascript language]] @@html:11-03-2026 16:52@@ @@html:learning@@ @@html:notes@@ diff --git a/push b/push new file mode 100755 index 0000000..b2a6d2f Binary files /dev/null and b/push differ diff --git a/push.c b/push.c new file mode 100755 index 0000000..df60743 --- /dev/null +++ b/push.c @@ -0,0 +1,29 @@ +#include +#include +#include + +int main() { + char path[100] = "/home/zaine/master-folder/org-platform/org_web"; + + char command[200]; + + snprintf(command, sizeof(command), "cd %s && git add .", path); + + int result = system(command); + + snprintf(command, sizeof(command), "cd %s && git commit -m \"Auto commit", path); + + result = system(command); + + snprintf(command, sizeof(command), "cd %s && git push", path); + + result = system(command); + + if (result == 0) { + printf("Successfully pushed files to git.\n"); + } else { + printf("Failed to push files to git.\n"); + } + + return 0; +} diff --git a/rl/index.org b/rl/index.org old mode 100644 new mode 100755 diff --git a/sitemap.org b/sitemap.org index 0bd2991..0e50a93 100755 --- a/sitemap.org +++ b/sitemap.org @@ -78,17 +78,17 @@ flowchart TD n30 --> n36 n37["Tag: website"] n30 --> n37 - n38["Tag: life"] + n38["Tag: update"] n30 --> n38 - n39["Tag: update"] + n39["Tag: life"] n30 --> n39 - n40["Tag: insights"] + n40["Tag: education"] n30 --> n40 - n41["Tag: emacs"] + n41["Tag: insights"] n30 --> n41 - n42["Tag: education"] + n42["Tag: reading"] n30 --> n42 - n43["Tag: reading"] + n43["Tag: emacs"] n30 --> n43 n44["Tag: maths"] n30 --> n44 @@ -211,12 +211,12 @@ flowchart TD click n35 "tags/notes.html" "Tag: notes" click n36 "tags/review.html" "Tag: review" click n37 "tags/website.html" "Tag: website" - click n38 "tags/life.html" "Tag: life" - click n39 "tags/update.html" "Tag: update" - click n40 "tags/insights.html" "Tag: insights" - click n41 "tags/emacs.html" "Tag: emacs" - click n42 "tags/education.html" "Tag: education" - click n43 "tags/reading.html" "Tag: reading" + click n38 "tags/update.html" "Tag: update" + click n39 "tags/life.html" "Tag: life" + click n40 "tags/education.html" "Tag: education" + click n41 "tags/insights.html" "Tag: insights" + click n42 "tags/reading.html" "Tag: reading" + click n43 "tags/emacs.html" "Tag: emacs" click n44 "tags/maths.html" "Tag: maths" click n46 "posts/posts-intro.html" "Posts Introduction" click n47 "posts/posts-list.html" "Posts List" @@ -301,12 +301,12 @@ flowchart TD - [[file:tags/notes.org][Tag: notes]] - [[file:tags/review.org][Tag: review]] - [[file:tags/website.org][Tag: website]] - - [[file:tags/life.org][Tag: life]] - [[file:tags/update.org][Tag: update]] - - [[file:tags/insights.org][Tag: insights]] - - [[file:tags/emacs.org][Tag: emacs]] + - [[file:tags/life.org][Tag: life]] - [[file:tags/education.org][Tag: education]] + - [[file:tags/insights.org][Tag: insights]] - [[file:tags/reading.org][Tag: reading]] + - [[file:tags/emacs.org][Tag: emacs]] - [[file:tags/maths.org][Tag: maths]] - posts - [[file:posts/posts-intro.org][Posts Introduction]] diff --git a/tests/resource-loader.test.js b/tests/resource-loader.test.js old mode 100644 new mode 100755