Prepare the blog

.github/workflows/deploy.yml

@@ -0,0 +1,43 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.ref != 'refs/heads/main'
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@main
+      - run: touch site/.nojekyll
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npm run abridge
+      - name: 'Build only'
+        uses: shalzz/[email protected]
+        env:
+          BUILD_DIR: .
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BUILD_ONLY: true
+
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@main
+      - run: touch site/.nojekyll
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npm run abridge
+      - name: 'Build and deploy'
+        uses: shalzz/[email protected]
+        env:
+          PAGES_BRANCH: gh-pages
+          BUILD_DIR: .
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,15 @@
+.env
+public
+themes
+build
+storage
+node_modules
+package-lock.json
+static/demo.html
+static/tinysearch_engine.js
+static/tinysearch_engine.d.ts
+static/tinysearch_engine_bg.wasm.d.ts
+static/package.json
+static/js/pagefind.*.pf_meta
+static/js/index
+static/js/fragment

CNAME

@@ -0,0 +1 @@
+blog.haskell.org

README.md

@@ -0,0 +1,53 @@
+# Haskell Blog
+
+## Local installation
+
+The blog is made with [Zola], based on the [Abridge theme].
+
+You will need:
+  * The `zola` binary v0.19.1 or higher
+  * `npm`
+
+Once you have cloned this repository, run `npm install` and `npm run abridge` to initialise the front-end features like full-text search.
+
+## Contribute content
+
+### Blog post structure
+
+#### Name
+
+Blog posts are located in the `content` directory, as markdown files. The files themselves start with the (expected) date of publication
+and contain their title in a "slug" format (alphanumeric characters, words separated by a hyphen, all lowercase):
+
+```
+2024-08-03-documentation-best-practices.md
+```
+
+#### Front-matter
+
+The file itself must contain a front-matter in TOML format that has the following properties:
+
+```
++++
+title = "Title of the post"
+date = YYYY-MM-DD
+[taxonomies]
+authors = ["Author's Name"] # The author's name. Will be indexed.
+categories = ["Haddock"] # A minima should be the name of the team ("Haddock", "HLS", "Cabal"). Will be indexed.
+tags = ["Practices"] # Something more precise like "Release", "Practice", "JavaScript", can be aded. Will be indexed.
++++
+```
+
+#### Summary
+
+The eye-catcher that you wish to show on the front-page of the blog is the first paragraph. 
+You can manually delimit where it ends by inserting `<!-- more -->` on a newline between this paragraph and the rest of the content.
+
+Otherwise, in the absence of this comment, the first 150 characters will be used by Zola
+
+### Local preview
+
+Run `zola serve --drafts` in order to serve the website and automatically render it when files change.
+
+[Zola]: https://www.getzola.org/
+[Abridge theme]: https://abridge.pages.dev/overview-abridge/

content/2024-08-03-documentation-best-practices.md

@@ -0,0 +1,137 @@
++++
+title = "Documentation Best Practices"
+date = 2024-08-02
+[taxonomies]
+authors = ["Hécate"]
+categories = ["Haddock"]
+tags = ["Practices"]
++++
+
+In the Haddock team, part of our mission is to help with writing documentation, and promoting best practices. This article will help you write the best documentation you can!
+
+<!-- more -->
+
+We  adapt documentation outside practices to our ecosystem, and leverage our own technologies to empower Haskell users with their documentation work.
+
+Let us see some of these techniques, and how the Haddock team can be of help.
+
+## Writing documentation for your software project
+
+### Justify yourself
+
+When you create software, there is a pipeline from your brain straight to your code. Your decisions — such as the libraries you’ve used,
+or your program architecture — shape how your code is structured and written.
+
+Unfortunately, simply writing the code isn’t enough.The reasoning behind the decisions you made is as important as the decisions themselves. In the short term, solving a problem may let you move ahead immediately, but what keeps you on the correct path is understanding what
+brought you to that solution.
+
+Indeed, your choices may not be as popular as you think they are! Of course, you decided on them because you already convinced yourself
+that they’re best. But you have a user base to convince as well, and they may not see things the same way you do.
+
+As such, it is vitally important to document which decisions you made and to justify why you made them. If it’s not immediately obvious 
+why a behaviour or a pattern exists, future maintainers might be tempted to drop it — only to discover too late why it was needed.
+
+### The reference flow of documentation
+
+Not all types of documentation have the same life cycle. Different pieces of documentation are more or less stable, and this determines
+which can act as a conceptual and theoretical foundation for your project.
+
+Examples of stable documentation include:
+
+* A README without code
+* A vision statement
+* The value proposition and the core domain
+
+These ought not to change much, because they describe the basic problems that your code aims to address, solve or support in the long run.
+While it is normal to fiddle around with the boundaries of your project at the beginning, in general these should change infrequently.
+
+Some other documentation is called volatile, like:
+
+* Documentation generated at runtime
+* Code examples
+* Tests
+* Configuration
+
+These  are *expected* to change frequently, as your project changes, your API evolves, and you change configuration options.
+Volatile documentation is expensive to maintain, but also very valuable, as it shows in a concrete way how the user can interact with
+your project.
+
+
+> “When you refer to something, make sure the direction of the reference is from the more volatile to the more stable elements”
+> -- Cyrille Martraire, Living Documentation, 2019
+
+
+As such, here is a simplified model of the documentation cascade for a typical Haskell project, from the most volatile to the most stable
+sources:
+
+```
+Haddocks of your library or a third-party library
+├──> Official specs for your domain
+├──> Architecture Document
+└─┬> Haddocks of a core library (base, text, vector, etc)
+  ├──> GHC Manual
+  ├──> Official specs for what the core libs provide
+  └──> Papers (without paywalls)
+```
+
+Keep in mind that while the Haddocks of a project can refer to the project specs, or to an architecture document, these documents should
+never refer to the project's current implementation. If you must refer to the code, point to where it's located.
+The (current, volatile) code cannot be the justification for the (planned, stable) architecture.
+
+The GHC manual is much more stable than the haddocks of a Core library, which is why documentation should flow from
+the library to the manual.
+
+Finally, papers serve the same purpose as architecture documents, where they describe techniques that may be implemented,
+but theyshould not point to code that is subject to change – lest they  point to a library that has evolved so much
+that it no longer relates to the paper.
+
+#### Example: The Set data structure
+
+The [Haddocks for the `Set` datatype](https://hackage.haskell.org/package/containers-0.6.5.1/docs/Data-Set.html)
+(from the `containers` library) are an example of documentation which follows this model well:
+
+* They point to an overview of the API ([here](https://haskell-containers.readthedocs.io/en/latest/set.html): _volatile_)
+* They refer to the papers that have informed the design of its implementation: the absence of working links may be annoying,
+but the references can still be followed (_stable_)
+
+### Understand for whom you write
+
+This section introduces the Diátaxis Framework for documentation:
+
+<img src="https://diataxis.fr/_images/diataxis.png" width=100%>
+
+> -- Diátaxis Framework, by Daniele Procida, https://diataxis.fr
+
+
+Diátaxis maps out the entire life cycle of one’s interaction with a system. Each of its four quadrants describes a different
+situation in which a user may find themselves.
+
+
+Diátaxis is not just about filling out all the quadrants like a checklist (although they are all good to have!).
+Instead, it is about understanding how each section focusses on a particular combination of user needs and situations.
+If a new user in need of actively acquiring some practice with the project, they can safely be pointed to the "Tutorials" part
+of your documentation, as it is the part that focuses on "_Acquisition_" of knowledge through "_Action_".
+The focus of the tutorial is to make a prospective user acquire basic competence in handling the software. It is an ice-breaker.
+
+However someone who is in need of a deeper – but perhaps less immediately applicable understanding of the project –
+will be better served by the Explanation, which serves the need for thought (or _Cognition_)
+
+
+In short, the message of Diátaxis is that you are not meant to write The One Documentation that covers everything — 
+inevitably, this produces documentation which is shallow due to its breadth. Instead, focus on the strategic aspects of your documentation,
+and you will produce documentation of better quality, with a clear purpose that it can fulfill more easily.
+
+Through the lens of Diátaxis, the module API documentation produced by Haddock is a *Reference*.
+
+## Reach Out
+
+Should you need any help in writing or proof-reading documentation, please stop by the [Matrix chatroom](https://matrix.to/#/#haddock:matrix.org) of the Haddock team,
+or ping us with the [@haddock](https://gitlab.haskell.org/groups/haddock/-/group_members?sort=last_joined) group tag on the
+[Haskell Gitlab](https://gitlab.haskell.org/). We would be more than happy to lend you a hand and discuss how to best serve your users,
+you included.
+
+## Read More
+
+* [Haddock manual](https://haskell-haddock.readthedocs.io/latest/)
+* [The theory behind Diátaxis](https://diataxis.fr/theory/)
+* [How to contribute to Haddock](https://gitlab.haskell.org/ghc/ghc/-/blob/master/utils/haddock/CONTRIBUTING.md?ref_type=heads)

content/_index.md

@@ -0,0 +1,5 @@
++++
+paginate_by = 3
+sort_by = "date"
+template = "index.html"
++++

content/archive/_index.md

@@ -0,0 +1,6 @@
++++
+template = "archive.html"
+
+[extra]
+sec = ""
++++

content/pages/_index.md

@@ -0,0 +1,3 @@
++++
+render = false
++++

content/pages/about.md

@@ -0,0 +1,16 @@
++++
+title = "About this blog"
+path = "about"
+template = "pages.html"
+draft = false
++++
+
+## About this blog
+
+Welcome to the Haskell Project's blog!
+
+This is the place where the various teams that power the language and its ecosystem communicate about their progress, innovations,
+and new releases.
+
+The Haskell.org Committee is the publisher of this website. Please contact us at `committee <at> haskell <dot> org` if you wish to
+signal content that goes against our [Guidelines For Respectful Communication](https://haskell.foundation/guidelines-for-respectful-communication/).

content/pages/privacy.md

@@ -0,0 +1,15 @@
++++
+title = "Privacy Policy"
+description = "This page outlines the Privacy Policy for this site, and the date at which this policy was put into affect."
+path = "privacy"
+template = "pages.html"
+draft = false
++++
+
+## Privacy
+
+- This site does not set or use cookies.
+- This site does not store data in the browser to be shared, sent, or sold to third-parties.
+- No personal information is shared, sent, or sold to third-parties.
+
+**Effective Date:** _1st Jan 2022_

content/static/stork_toml.md

@@ -0,0 +1,5 @@
++++
+path = "data_stork"
+template = "stork_toml.html"
+draft = true
++++

content/static/tinysearch_json.md

@@ -0,0 +1,5 @@
++++
+path = "data_tinysearch"
+template = "tinysearch_json.html"
+draft = true
++++

package.json

@@ -0,0 +1,20 @@
+{
+  "name": "abridge-bundle",
+  "version": "2.0.0",
+  "description": "Abridge - set PWA cache files list, bundle and minify js",
+  "author": "Jake G <[email protected]>",
+  "license": "MIT",
+  "homepage": "https://github.com/Jieiku/abridge",
+  "scripts": {
+    "abridge": "node -e \"if ( require('fs').existsSync('./themes/abridge/package_abridge.js')) {require('fs').copyFileSync('./themes/abridge/package_abridge.js', './package_abridge.js')}\" && node package_abridge.js",
+    "search:pagefind": "node -e \"if ( require('fs').existsSync('./themes/abridge/static/js/searchChange.js')) {require('fs').copyFileSync('./themes/abridge/static/js/searchChange.js', './static/js/searchChange.js')}\" && node ./static/js/searchChange.js --pagefind",
+    "search:elasticlunr": "node -e \"if ( require('fs').existsSync('./themes/abridge/static/js/searchChange.js')) {require('fs').copyFileSync('./themes/abridge/static/js/searchChange.js', './static/js/searchChange.js')}\" && node ./static/js/searchChange.js --elasticlunr"
+  },
+  "dependencies": {
+    "fast-toml": "^0.5.4",
+    "jsonminify": "^0.4.2",
+    "pagefind": "^1.1.0",
+    "replace-in-file": "^8.1.0",
+    "uglify-js": "^3.17.4"
+  }
+}