daily-writing 0.1.0__tar.gz

daily_writing-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.3
+Name: daily-writing
+Version: 0.1.0
+Summary: Python-based static site generator for writing challenges (such as writober)
+Author: Joachim Jablon
+Author-email: Joachim Jablon <ewjoachim@gmail.com>
+Requires-Dist: htpy>=25.10.0
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: pydantic-extra-types[pycountry]>=2.10.6
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: brotli>=1.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: fonttools>=4.60.1
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: feedgen>=1.0.0
+Requires-Dist: tzlocal>=5.3.1
+Requires-Dist: babel>=2.17.0
+Requires-Dist: langcodes>=3.5.1
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: flowmark>=0.6.1
+Requires-Dist: markdown-it-py[plugins]>=4.0.0
+Requires-Dist: yarl>=1.24.2
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Dist: fastapi>=0.121.0 ; extra == 'server'
+Requires-Dist: pdbpp>=0.11.7 ; extra == 'server'
+Requires-Dist: uvicorn>=0.38.0 ; extra == 'server'
+Requires-Dist: watchfiles>=1.1.1 ; extra == 'server'
+Requires-Dist: websockets>=15.0.1 ; extra == 'server'
+Requires-Python: >=3.14
+Provides-Extra: server
+Description-Content-Type: text/markdown
+
+# Daily Writing
+
+This repo hosts an open source project that let you create a website presenting
+daily writings, it was created with challenges like Writober or Writever in mind, but
+it's not tied to a specific challenge.
+
+Daily Writing mainly turns a bunch of markdown files (one per writing, at most one per
+day), a configuration file, and a directory of static files into a static HTML website
+that can be deployed.
+
+Daily Writing offers various features, such as:
+- A page for each writing and a homepage. A menu displaying a calendar with all the
+  writing for all months.
+- Each day is linked to a "prompt" (as in writever/writober prompt), and can have a
+  title distinct from the prompt. This is useful if the title of your writing isn't
+  excatly the prompt you were given for the day. Also, if your prompts are in a given
+  language and the title is the prompt you translated to your language, it's nice.
+  The prompt will be displayed in the menu over the title.
+- A given writing can span over multiple days and their associated prompts (e.g. if
+  you're late), and the calendar will reflect that. Those days may even be
+  non-consecutive. It's assumed that the title will be composed of multiple parts each
+  related to the associated prompts.
+- Each day in a month is linked to a unique color, and the calendar is colored
+  accordingly. The homepage displays all the month's colors.
+- Posts can be written in advance and will only be published of their date.
+- Links to the previous and next writings, for binge-reading.
+- Most metadata can be extracted from the name of the file and the writing markdown
+  title, but can then be normalized to frontmatter. Having a frontmatter is necessaryÒ when
+  using a CMS editor.
+- Writings spanning multiple days will have a gradient between the colors of the days.
+- A CMS, at `/admin` to update your writings and the site settings directly from your
+  browser.
+- A RSS feed.
+- Nice preview images when you post links to social networks.
+- Discreet links to the GitHub source of each writing, to ease online edition or typo
+  reporting.
+- Privacy-minded Google fonts, downloaded and optimized at build time so that you can
+  get various fonts without offering your reader's data to Google (damn, that was a
+  mess to code)
+- Dark mode. No light mode. Contributions welcome on that.
+- Support for extra custom CSS. If you want to add a light mode but just for yourself.
+- Support of various locales, for date formats. Apart from dates and numbers, all the
+  words that appear on the interface are configurable, so technically, we support all
+  languages that Unicode supports.
+- If you rename a file but want to keep its original URL too, you can add aliases.
+
+Author's personal undying love of handcrafted open source and meticulous yak shaving
+went into this project. He likes to think that it shows.
+
+## An example:
+
+https://writober.ewjoach.im/ is deployed from https://github.com/ewjoachim/writober,
+using this project.
+
+## Extraction rules
+
+From a single file without a frontmatter, these are the informations being extracted.
+Say the file is at `2026/10/03-hello.md` and its content starts with a title that says:
+`# 03 - Bonjour`. The system will find that this writing covers a single day
+(`2026-10-03`), its prompt is "hello" and its official title is "Bonjour".
+
+Say the file is at `2026/10/03-hello-darkness.md` and its content starts with a title
+that says: `# 03&04 - Bonjour, Obscurité`. The system will find that this writing covers
+2 days:
+- `2026-10-03` for which the prompt is `hello` and the title `Bonjour`,
+- `2026-10-04` for which the prompt is `darkness` and the title `Obscurité`.
+
+You can always override those values by editing the frontmatter.
+
+## Installation
+
+### Github
+
+- [Create a repository from the template](https://repo.new?template_name=daily-writing-template&template_owner=ewjoachim)
+- Adjust configuration with your details
+- Your repository is deployed through GitHub actions (`https://<username>.github.io/<repo name>`)
+- Write your stories
+
+### Elsewhere
+
+(Feel free to contribute installation instructions for other platforms).
+
+## Configuration
+
+Your website can be configured through either:
+
+- `daily-writing.toml`,
+- `pyproject.toml` within the `[tool.daily-writing]` section
+- environments variables,
+- CLI flags.
+
+The same options are available in all ways, but they're not spelled out exactly the
+same way. In the toml configuration and environment variables, words are
+separated by `_` (underscores). In the flags, they're separated by `-` (dashes).
+Environment variables are all upper case and prefixed with `DAILY_WRITING_`
+
+Examples:
+
+- `daily-writing.toml`: `server_url = "https://writober.ewjoach.im"`
+- environments variables: `SERVER_URL="https://writober.ewjoach.im"`
+- CLI flags: `--server-url="https://writober.ewjoach.im"`
+
+The easiest and most up-to-date way to learn about every configuration option is
+through: `daily-writing -h`. Feel free to consult [daily-writing.toml](https://github.com/ewjoachim/writober/blob/main/daily-writing.toml) for a working example.
+
+> [!NOTE] There is one extra configuration element: setting the `GITHUB_TOKEN`
+> environment variable will help you avoid rate limiting to GitHub's API. It's not added
+> in the normal configuration elements to avoid accidentally committing it to your
+> repository.
+
+## CLI
+
+There are 2 main subcommands:
+
+- `daily-writing build` builds the website
+- `daily-writing serve` launches a local development server that autobuilds the
+  website and auto-reload pages in your browser when changes are detected.
+
+## CI/CD Deployment
+
+Solutions like [GitHub Pages](https://docs.github.com/en/pages), [Cloudflare
+Pages](https://developers.cloudflare.com/pages/), [GitLab
+Pages](https://docs.gitlab.com/user/project/pages/), etc will make your life easier, as
+you can edit the markdown files online or push them through git, and have them get
+redeployed automatically daily and upon changes.
+
+Here's a GitHub Actions workflow example:
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+  schedule:
+    - cron: "1 22,23 * 10 *" # Adjust to whenever relvant to you
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Sphinx build
+        run: uv run daily-writing build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: _build
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+## Adding new content
+
+### Manual
+Add and edit your markdown files in the repository via Git or via your
+platform's Web interface.
+
+### Online
+Daily-Writing can come with a [CMS](https://github.com/sveltia/sveltia-cms), allowing
+you to get a nice admin interface that doesn't require to interact with Git.
+
+Integration is not yet 100% streamlined, but it's coming.

daily_writing-0.1.0/README.md

@@ -0,0 +1,190 @@
+# Daily Writing
+
+This repo hosts an open source project that let you create a website presenting
+daily writings, it was created with challenges like Writober or Writever in mind, but
+it's not tied to a specific challenge.
+
+Daily Writing mainly turns a bunch of markdown files (one per writing, at most one per
+day), a configuration file, and a directory of static files into a static HTML website
+that can be deployed.
+
+Daily Writing offers various features, such as:
+- A page for each writing and a homepage. A menu displaying a calendar with all the
+  writing for all months.
+- Each day is linked to a "prompt" (as in writever/writober prompt), and can have a
+  title distinct from the prompt. This is useful if the title of your writing isn't
+  excatly the prompt you were given for the day. Also, if your prompts are in a given
+  language and the title is the prompt you translated to your language, it's nice.
+  The prompt will be displayed in the menu over the title.
+- A given writing can span over multiple days and their associated prompts (e.g. if
+  you're late), and the calendar will reflect that. Those days may even be
+  non-consecutive. It's assumed that the title will be composed of multiple parts each
+  related to the associated prompts.
+- Each day in a month is linked to a unique color, and the calendar is colored
+  accordingly. The homepage displays all the month's colors.
+- Posts can be written in advance and will only be published of their date.
+- Links to the previous and next writings, for binge-reading.
+- Most metadata can be extracted from the name of the file and the writing markdown
+  title, but can then be normalized to frontmatter. Having a frontmatter is necessaryÒ when
+  using a CMS editor.
+- Writings spanning multiple days will have a gradient between the colors of the days.
+- A CMS, at `/admin` to update your writings and the site settings directly from your
+  browser.
+- A RSS feed.
+- Nice preview images when you post links to social networks.
+- Discreet links to the GitHub source of each writing, to ease online edition or typo
+  reporting.
+- Privacy-minded Google fonts, downloaded and optimized at build time so that you can
+  get various fonts without offering your reader's data to Google (damn, that was a
+  mess to code)
+- Dark mode. No light mode. Contributions welcome on that.
+- Support for extra custom CSS. If you want to add a light mode but just for yourself.
+- Support of various locales, for date formats. Apart from dates and numbers, all the
+  words that appear on the interface are configurable, so technically, we support all
+  languages that Unicode supports.
+- If you rename a file but want to keep its original URL too, you can add aliases.
+
+Author's personal undying love of handcrafted open source and meticulous yak shaving
+went into this project. He likes to think that it shows.
+
+## An example:
+
+https://writober.ewjoach.im/ is deployed from https://github.com/ewjoachim/writober,
+using this project.
+
+## Extraction rules
+
+From a single file without a frontmatter, these are the informations being extracted.
+Say the file is at `2026/10/03-hello.md` and its content starts with a title that says:
+`# 03 - Bonjour`. The system will find that this writing covers a single day
+(`2026-10-03`), its prompt is "hello" and its official title is "Bonjour".
+
+Say the file is at `2026/10/03-hello-darkness.md` and its content starts with a title
+that says: `# 03&04 - Bonjour, Obscurité`. The system will find that this writing covers
+2 days:
+- `2026-10-03` for which the prompt is `hello` and the title `Bonjour`,
+- `2026-10-04` for which the prompt is `darkness` and the title `Obscurité`.
+
+You can always override those values by editing the frontmatter.
+
+## Installation
+
+### Github
+
+- [Create a repository from the template](https://repo.new?template_name=daily-writing-template&template_owner=ewjoachim)
+- Adjust configuration with your details
+- Your repository is deployed through GitHub actions (`https://<username>.github.io/<repo name>`)
+- Write your stories
+
+### Elsewhere
+
+(Feel free to contribute installation instructions for other platforms).
+
+## Configuration
+
+Your website can be configured through either:
+
+- `daily-writing.toml`,
+- `pyproject.toml` within the `[tool.daily-writing]` section
+- environments variables,
+- CLI flags.
+
+The same options are available in all ways, but they're not spelled out exactly the
+same way. In the toml configuration and environment variables, words are
+separated by `_` (underscores). In the flags, they're separated by `-` (dashes).
+Environment variables are all upper case and prefixed with `DAILY_WRITING_`
+
+Examples:
+
+- `daily-writing.toml`: `server_url = "https://writober.ewjoach.im"`
+- environments variables: `SERVER_URL="https://writober.ewjoach.im"`
+- CLI flags: `--server-url="https://writober.ewjoach.im"`
+
+The easiest and most up-to-date way to learn about every configuration option is
+through: `daily-writing -h`. Feel free to consult [daily-writing.toml](https://github.com/ewjoachim/writober/blob/main/daily-writing.toml) for a working example.
+
+> [!NOTE] There is one extra configuration element: setting the `GITHUB_TOKEN`
+> environment variable will help you avoid rate limiting to GitHub's API. It's not added
+> in the normal configuration elements to avoid accidentally committing it to your
+> repository.
+
+## CLI
+
+There are 2 main subcommands:
+
+- `daily-writing build` builds the website
+- `daily-writing serve` launches a local development server that autobuilds the
+  website and auto-reload pages in your browser when changes are detected.
+
+## CI/CD Deployment
+
+Solutions like [GitHub Pages](https://docs.github.com/en/pages), [Cloudflare
+Pages](https://developers.cloudflare.com/pages/), [GitLab
+Pages](https://docs.gitlab.com/user/project/pages/), etc will make your life easier, as
+you can edit the markdown files online or push them through git, and have them get
+redeployed automatically daily and upon changes.
+
+Here's a GitHub Actions workflow example:
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+  schedule:
+    - cron: "1 22,23 * 10 *" # Adjust to whenever relvant to you
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Sphinx build
+        run: uv run daily-writing build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: _build
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+## Adding new content
+
+### Manual
+Add and edit your markdown files in the repository via Git or via your
+platform's Web interface.
+
+### Online
+Daily-Writing can come with a [CMS](https://github.com/sveltia/sveltia-cms), allowing
+you to get a nice admin interface that doesn't require to interact with Git.
+
+Integration is not yet 100% streamlined, but it's coming.

daily_writing-0.1.0/daily_writing/__main__.py

@@ -0,0 +1,44 @@
+import logging
+
+from . import build, normalize
+from . import settings as settings_module
+
+
+class NoCommandSelected(Exception):
+    pass
+
+
+class MissingExtraDependency(Exception):
+    pass
+
+
+def main():
+    settings = settings_module.Settings()  # pyright: ignore[reportCallIssue]
+    logging.basicConfig(level=settings.verbosity)
+    logging.getLogger("fontTools").setLevel("WARNING")
+    logging.getLogger("markdown_it.rules_block").setLevel("INFO")
+
+    match settings.subcommand:
+        case settings_module.Build():
+            build.build(settings=settings)
+        case settings_module.Serve():
+            serve_website(settings=settings)
+        case settings_module.Normalize():
+            normalize.normalize(settings=settings)
+        case None:
+            raise NoCommandSelected("No command selected")
+
+
+def serve_website(settings: settings_module.Settings):
+    try:
+        from . import serve  # noqa: PLC0415
+    except ImportError as exc:
+        raise MissingExtraDependency(
+            "Extra dependencies `server` is required for daily-writing serve (`pip install daily-writing[server]`)"
+        ) from exc
+
+    serve.serve(settings=settings)
+
+
+if __name__ == "__main__":
+    main()

daily_writing-0.1.0/daily_writing/artifacts.py

@@ -0,0 +1,58 @@
+import io
+import pathlib
+from typing import Protocol, override
+
+import pydantic
+from pydantic import dataclasses as pdataclasses
+
+
+class BaseArtifact(Protocol):
+    def write(self, destination: pathlib.Path): ...
+
+
+@pdataclasses.dataclass(kw_only=True)
+class TextArtifact:
+    path: pathlib.Path
+    contents: str
+
+    def write(self, destination: pathlib.Path):
+        if self.path.is_absolute():
+            raise ValueError("Only relative paths are accepted")
+
+        (destination / self.path).parent.mkdir(exist_ok=True, parents=True)
+        (destination / self.path).write_text(self.contents)
+
+
+@pdataclasses.dataclass(kw_only=True)
+class HTMLArtifact(TextArtifact):
+    @override
+    def write(self, destination: pathlib.Path):
+        super().write(destination=destination)
+
+
+@pdataclasses.dataclass(
+    kw_only=True, config=pydantic.ConfigDict(arbitrary_types_allowed=True)
+)
+class BytesArtifact:
+    path: pathlib.Path
+    contents: io.BytesIO
+
+    def write(self, destination: pathlib.Path):
+        if self.path.is_absolute():
+            raise ValueError("Only relative paths are accepted")
+
+        (destination / self.path).parent.mkdir(exist_ok=True, parents=True)
+        (destination / self.path).write_bytes(self.contents.getvalue())
+
+
+@pdataclasses.dataclass(kw_only=True)
+class FileArtifact:
+    path: pathlib.Path
+    source: pathlib.Path
+    destination: pathlib.Path
+
+    def write(self, destination: pathlib.Path):
+        rel = self.path.relative_to(self.source)
+        destination = destination / self.destination / rel
+        destination.parent.mkdir(exist_ok=True, parents=True)
+        self.path.copy(destination)

daily_writing-0.1.0/daily_writing/atom.py

@@ -0,0 +1,51 @@
+import datetime
+import io
+import pathlib
+import zoneinfo
+from typing import cast
+
+from feedgen.feed import FeedGenerator
+from pydantic import dataclasses as pdataclasses
+
+from daily_writing import artifacts
+
+from . import settings as settings_module
+
+
+@pdataclasses.dataclass(kw_only=True)
+class FeedEntryArtifact:
+    artifact_id: str
+    title: str
+    link: str
+    date: datetime.date
+
+
+class Feed:
+    def __init__(self, settings: settings_module.Settings):
+        self.feed_gen: FeedGenerator = FeedGenerator()
+        self.feed_gen.id(str(settings.site_full_url))
+        self.feed_gen.title(settings.site_name)
+        self.feed_gen.author(name=settings.author)
+        self.feed_gen.link(href=str(settings.site_full_url), rel="self")
+        self.feed_gen.subtitle(settings.description)
+        self.feed_gen.language(str(settings.locale.locale))
+        self.timezone: str = settings.timezone
+        self.atom_path: pathlib.Path = settings.atom_path
+
+    def add_entry(self, item_id: str, title: str, link: str, date: datetime.date):
+        entry = self.feed_gen.add_entry()  # pyright: ignore[reportUnknownVariableType]
+        entry.id(item_id)
+        entry.title(title)
+        entry.link(href=link)
+        entry.updated(
+            datetime.datetime.combine(
+                date, datetime.time(), tzinfo=zoneinfo.ZoneInfo(self.timezone)
+            ).isoformat()
+        )
+
+    def get_artifact(self) -> artifacts.BytesArtifact:
+        contents: bytes = cast(bytes, self.feed_gen.atom_str(pretty=True))
+
+        return artifacts.BytesArtifact(
+            path=self.atom_path, contents=io.BytesIO(contents)
+        )