Skip to content

A theme is one file, and the deck's settings are named as the deck's - #24

Merged
fabeat merged 10 commits into
mainfrom
feature/theme-files
Nov 4, 2026
Merged

fabeat merged 10 commits into
mainfrom
feature/theme-files

Conversation

@fabeat

@fabeat fabeat commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

The site says what the libraries now do.

The libraries have changed on their own branches: a theme is one file in both halves, and the slides half has gained a deck-settings: layer. Nine pages carried the old story and every one of them changes — the themes page, the directives page, the errors page, the Word configuration and templates pages, the general files page and the command line's theme page.

The reference tables are read against the code through the path repositories, and two of them had to change: the slides half's StyleSlots is gone with the file it read, and the frontmatter table has sixteen keys.

The skill

The bundle is a copy made by the build, so a page that changes changes the copy — and five of the nine pages were already carried.

The four slides-half pages were not carried at all, so the slides half's theme format and deck-settings: would have reached the site but not an agent using the skill. The bundle's own manifest gives the precedent:

The slides half's command line is carried: the bundle claims to be about decks as well as about documents, and a page that is not there is a page an agent cannot read.

They are carried now, and "Markdown Presentation" joins the bundle's sections — so every page of that section is one that must be carried, and a page added later and not carried is a failure the checker names rather than a gap nobody notices.

One thing is left undone and said so on the page: the bundle copies the Word half's gallery wholesale, and the slides half's nineteen decks are not in it. An agent that reads the slides half's pages has no deck to look at. That is a larger question than this change, and it is named rather than fixed quietly.

The gates

  • npm run build:strict, check-reference.php, pest, check-site-links.php, check-command-line.php and check-skill.php — all green.
  • New claim tests: the deck's settings, and the retired files' refusals, checked against the library rather than against the prose.

The two libraries read a theme out of one file now, and the slides half has a
layer for the deck's own settings. The pages said what they did before, and
that was five files, a `styles.yml` nobody read, a `layouts.yml` of its own and
fifteen frontmatter keys.

The reference tables are corrected against the code as it is: the slides half's
theme keys gain the two sections, its exceptions lose `UnknownStyleSlot` and
gain `RetiredThemeFile`, and its frontmatter gains `deck-settings`. The
`StyleSlots` class the tables asked for is gone from the slides half, so the
style slots are asked of the Word half alone.

The site's own finder holds a theme for each half, because a theme file serves
one of them and each half refuses the other's keys.
The bundle claimed to be about decks as well as about documents, and carried
the slides half's command line because of it. The slides half's own pages were
not carried, so the slides half's theme format and the deck's settings reached
the site and not an agent reading the bundle — and a bundle that taught only
the Word half's one-file theme would teach half of it.

"Markdown Presentation" joins the sections, so a page added to that section and
not carried is a failure the checker names rather than a gap nobody notices,
and the four pages are carried under names that say which section they are
from.

The slides half's own gallery of decks is still not in the bundle, and both the
skill and the page that describes it now say so.
The Word half's refusal names the path of the file beside the theme, not the
file's name, and the page quoted the name. The ellipsis is the path's shape.
@fabeat

fabeat commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

The CI is red until the libraries are merged, and the reason is in the workflow.

This repository's CI checks the two libraries out at a ref the repository variables name:

MARKDOWN_WORD_REF: ${{ github.event_name == 'pull_request' && vars.MARKDOWN_WORD_REF || 'main' }}
MARKDOWN_PRESENTATION_REF: ${{ github.event_name == 'pull_request' && vars.MARKDOWN_PRESENTATION_REF || 'main' }}

Both variables are main at the moment, and main does not have the change this pull request is about — so the suite runs against a library that does not know a theme is one file, and the theme tests fail against it.

Two ways to see it green:

  • merge markdown-presentation#47 and markdown-word#53 first, and this pull request's CI is green on the next run; or
  • point the variables at the branches — MARKDOWN_PRESENTATION_REF=feature/theme-files and MARKDOWN_WORD_REF=feature/theme-files — and re-run the jobs. That is what the variables are for.

The suite passes locally against the libraries on their branches, and the round trip the command depends on — the theme it writes, read back by the library's own reader — is the test that proves the format agrees.

…em guard them

The two halves' vocabularies overlap, so a theme file that carries only a name
and a named style is read by both, and the pages said one file cannot be both.
The slides half did read the styles file it loaded, so the page says it loaded
it and never used it. The example titled "every slide" had one slide, and the
index page still called a theme a directory.

The pages that were corrected are the ones that carry the correction, so the
claims are in tests and in the list of phrases the site must not say again.

The command line has changed since the branch was written: it refuses to write
a theme beside a file of the old format, and a role the deck has no layout for
takes the library's own name rather than nothing. The page says both, and the
sample report it quotes is the program's own output, rebuilt from the fixture
the report was made from.
…y so

The suite's two halves share a theme's name, its description, its author and its
named text styles, so a theme file carrying only those is read by both. What they
part at is the look, and a file carrying the other half's look is refused.

The files page and the themes page said the two halves keep separate vocabularies,
which is not so, and both libraries have corrected the claim. The pages now say it
as the libraries do, and the phrase is in the list of claims the site must not make
again.
@fabeat

fabeat commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

The CI is red for one reason, and it is the workflow's own doing — not this branch.

This repository's CI checks the two libraries out at a ref the repository variables name:

MARKDOWN_WORD_REF: ${{ github.event_name == 'pull_request' && vars.MARKDOWN_WORD_REF || 'main' }}
MARKDOWN_PRESENTATION_REF: ${{ github.event_name == 'pull_request' && vars.MARKDOWN_PRESENTATION_REF || 'main' }}

Both variables are main, and main does not have the change — so the suite runs against a library that does not know a theme is one file, and the theme tests fail against it. The failure says so plainly:

Error: Class "MarkdownPresentation\Exception\RetiredThemeFile" not found

That class exists only on markdown-presentation's branch. The site's build says the same thing about deck-settings: and about a theme's styles: section.

Two ways to see it green:

  • merge markdown-presentation#47 and markdown-word#53 first, and this pull request's CI is green on the next run; or
  • point the variables at the branches — MARKDOWN_PRESENTATION_REF=feature/theme-files and MARKDOWN_WORD_REF=feature/theme-files — and re-run the jobs. That is what the variables are for.

The suite passes locally against the libraries on their branches.

A review of all four pull requests is done and every finding is fixed. The findings for this repository were:

  • theme init wrote a theme the library then refused, and said it had succeeded — a retired layouts.yml beside the theme it wrote. It now refuses to write into such a directory, with or without --force, and says so in the library's own words.
  • a role the deck has no layout for could end up sharing a layout name with another role. Two roles on one name are one layout drawn twice, so a role whose library name is already one of the deck's own layout names now takes a name of its own.
  • the breaking change for existing users was not in this changelog. It is now.
  • a deck with an empty master part crashed with a ValueError and a stack trace. It is now a sentence.
  • a test asserted the loaded theme rather than the file, so it passed whether or not the layouts: section was written. It now reads the file.

The report the command prints, the file it writes and the change to the changelog are all consistent with each other; the site's copy of the sample report was checked against the program's own output, character for character.

…is named

The bundle carried the Word half's own gallery and said so, and said that the
slides half's was not in it. It is now carried beside the Word half's, and the
examples the site shows are in examples/site/ beside them: three directories
under examples/, each named for where its examples come from.

The themes are not carried with them. They ship with the library, and the
resolver's last step is the theme that ships with the package, so an agent who
has installed the library can build every deck in either gallery. A theme a
deck names by a path is written from the deck's own directory, and that
directory is carried whole, so it travels with the copy.

The copy is made by the build, so it cannot drift while the build runs — but a
bundle built against another checkout can, and nothing said so. The checker
compares both galleries with the libraries, byte for byte, the way it already
compares the scripts, and the pages that describe the bundle are the ones that
say what it carries.

The loop and the command line named only the Word half, while the bundle
describes decks and carries four pages about them. Both now cover the slides
half, and the description says a document or a deck.
… them guard them

A theme is one file and the pages that said otherwise now say so. The slides
half's themes page carries a whole theme, the quoting a colour needs, the three
faces, the ten refusals of a named style, the folding of a style's name and the
rules a master and a `layouts:` section follow; the Word half carries its own
refusals. The resolution order is the one the Word half gives, the theme's name
comes back out of a deck, a deck's own settings come back as the slides' own,
and the frontmatter does not survive a round trip at all.

Every claim is checked against the library that has to behave that way, and the
phrases that were wrong are named so that they cannot come back.
@sonarqubecloud

sonarqubecloud Bot commented Nov 4, 2026

Copy link
Copy Markdown

@fabeat
fabeat merged commit cc0c90b into main Nov 4, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant