# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """`paperspec site`: the Markdown renderer, the page layout and the folder the build writes.""" import json import pathlib import re import pytest from conftest import ROOT from paperspec.cli import main as cli_main, site GUIDE = """\ # Guide Intro with `code `, and a [link](other.md#part) to **bold** and *emphasis* text. ## Part ### Part 1. first 2. second - nested a - nested b 3. third - bullet with a second paragraph - tail lazy line 5. five | Name | Value | | --- | --- | | `a|b` | 1 | | c | 2 | Term : Definition of the term continued ```python if a < b: print("x") ``` closing paragraph """ class TestInline: @pytest.mark.parametrize( ("source", "html"), [ ("plain text", "plain text"), ("a *b* c", "a b c"), ("a **b** c", "a b c"), ( "**bold *and em* inside**", "bold and em inside", ), ("2*3*4", "2*3*4"), ("a * b * c", "a * b * c"), ("`x < y`", "x < y"), ("``a`b``", "a`b"), ("`*not em*`", "*not em*"), ("a & b < c", "a & b < c"), ( "", 'https://e.org/a?b=1&c=2', ), ("[text](https://e.org)", 'text'), ("[text](docs/a.md#frag)", 'text'), ("[**b**](README.md)", 'b'), ("[`c`](a.md)", 'c'), ], ) def test_renders_the_constructs_the_documentation_uses(self, source, html): assert site.inline(source) == html @pytest.mark.parametrize( ("source", "text"), [ ("`code` and [link](x.md) and **strong**", "code and link and strong"), (" padded ", "padded"), ("*emphasis*", "emphasis"), ], ) def test_plain_drops_the_markup(self, source, text): assert site.plain(source) == text class TestLinks: @pytest.mark.parametrize( ("target", "href"), [ ("https://example.org/a.md", "https://example.org/a.md"), ("mailto:a@b.c", "mailto:a@b.c"), ("/abs/path.md", "/abs/path.md"), ("#frag", "#frag"), ("a.md", "a.html"), ("dir/b.md#sec", "dir/b.html#sec"), ("README.md", "./"), ("dir/README.md", "dir/"), ("dir/README.md#x", "dir/#x"), ("file.json", "file.json"), ("../up.md", "../up.html"), ], ) def test_markdown_targets_become_page_links(self, target, href): assert site.rewrite_href(target) == href @pytest.mark.parametrize( ("heading", "anchor"), [ ("Hello, World!", "hello-world"), ("`code` and **bold**", "code-and-bold"), ("Part 2.1 \u2013 Results", "part-21--results"), ("snake_case name", "snake_case-name"), (" Padded ", "padded"), ("Ångström units", "ångström-units"), ], ) def test_slug_follows_the_forge_rule(self, heading, anchor): assert site.slug(heading) == anchor @pytest.mark.parametrize( ("md", "path", "url"), [ ("README.md", "index.html", ""), ("docs/overview.md", "docs/overview.html", "docs/overview.html"), ("docs/README.md", "docs/index.html", "docs/"), ("CHANGELOG.md", "CHANGELOG.html", "CHANGELOG.html"), ], ) def test_where_a_page_goes(self, md, path, url): assert site.page_path(md) == path assert site.page_url(md) == url def test_the_vocabulary_page_has_its_own_address(self): assert site.page_url("vocab") == "vocab/" @pytest.mark.parametrize( ("source", "target", "link"), [ ("index.html", "", "./"), ("index.html", "docs/a.html", "docs/a.html"), ("docs/a.html", "docs/b.html", "b.html"), ("docs/a.html", "", "../"), ("docs/a.html", "docs/", "./"), ("docs/deep/a.html", "docs/", "../"), ("docs/a.html", "schemas/x.json", "../schemas/x.json"), ("docs/a.html", "vocab/", "../vocab/"), ], ) def test_relative_links_between_pages(self, source, target, link): assert site.rel(source, target) == link @pytest.mark.parametrize( ("size", "text"), [ (0, "0 B"), (1023, "1023 B"), (1024, "1.0 KB"), (1536, "1.5 KB"), (5 * 1024**2, "5.0 MB"), (5 * 1024**3, "5120.0 MB"), ], ) def test_sizes_read_in_the_nearest_unit(self, size, text): assert site.size_text(size) == text class TestBlocks: def render(self, text): body, renderer = site.render_markdown(text) return body, renderer def test_a_heading_gets_an_id_and_the_first_h1_is_the_title(self): body, renderer = self.render("# Title\n\n## Sub *one*\n") assert body == ( '

Title

\n' '

Sub one' '#

' ) assert renderer.title == "Title" assert renderer.headings == [ {"level": 1, "text": "Title", "id": "title"}, {"level": 2, "text": "Sub one", "id": "sub-one"}, ] def test_equal_headings_get_numbered_ids_like_the_forge_does(self): _, renderer = self.render("## Part\n\n### Part\n\n## Part\n") assert [h["id"] for h in renderer.headings] == ["part", "part-1", "part-2"] def test_a_page_without_an_h1_has_no_title(self): _, renderer = self.render("## Only\n") assert renderer.title is None def test_only_the_first_h1_names_the_page(self): _, renderer = self.render("# One\n\n# Two\n") assert renderer.title == "One" def test_consecutive_lines_form_one_paragraph(self): body, _ = self.render("one\ntwo\n\nthree\n") assert body == "

one\ntwo

\n

three

" def test_a_fenced_block_keeps_its_text_and_names_its_language(self): body, _ = self.render("```python\nif a < b:\n pass\n```\n") assert ( body == '
if a < b:\n    pass
' ) def test_a_fence_without_a_language_has_no_class(self): body, _ = self.render("```\n# not a heading\n```\n") assert body == "
# not a heading
" def test_an_indented_fence_is_dedented(self): body, _ = self.render(" ```\n a\n b\n ```\n") assert body == "
a\n  b
" def test_a_table_has_a_head_and_a_body(self): body, _ = self.render("| A | B |\n| --- | :-: |\n| `x|y` | 2 |\n") assert body == ( '
' "
AB
x|y2
" ) def test_rows_may_leave_out_the_closing_pipe(self): body, _ = self.render("| A | B\n| --- | ---\n| c | d\n") assert body == ( '
' "
AB
cd
" ) def test_a_table_without_a_rule_row_has_only_body_rows_after_the_first(self): body, _ = self.render("| A | B |\n| c | d |\n") assert "AB" in body assert "cd" in body def test_a_definition_list(self): body, _ = self.render("Term\n: Meaning\n more\n\nOther\n: Second\n") assert body == ( "
Term
Meaning\nmore
Other
Second
" ) def test_a_bullet_list(self): body, _ = self.render("- a\n- b\n") assert body == "
  • a
  • b
" def test_an_ordered_list_keeps_its_start(self): body, _ = self.render("3. c\n4. d\n") assert body == '
  1. c
  2. d
' def test_a_nested_list(self): body, _ = self.render("- a\n - b\n - c\n- d\n") assert body == ( "
  • a

    \n
    • b
    • c
  • d
" ) def test_an_item_with_two_paragraphs(self): body, _ = self.render("- a\n\n more\n- b\n") assert body == "
  • a

    \n

    more

  • b
" def test_an_unindented_line_continues_the_item(self): body, _ = self.render("- a\nlazy\n") assert body == "
  • a\nlazy
" def test_a_blank_line_between_items_keeps_one_list(self): body, _ = self.render("- a\n\n- b\n") assert body == "
  • a
  • b
" def test_a_list_of_another_kind_starts_a_new_list(self): body, _ = self.render("- a\n1. b\n") assert body == "
  • a
\n
  1. b
" def test_a_block_ends_a_paragraph(self): body, _ = self.render("text\n# Heading\n") assert body == '

text

\n

Heading

' def test_empty_input_renders_nothing(self): assert self.render("")[0] == "" assert self.render("\n\n \n")[0] == "" def test_the_guide_renders_every_construct_once(self): body, renderer = self.render(GUIDE) assert body.count("") == 1 assert body.count("
") == 1 assert body.count("
") == 1
        assert body.count("
  • five
  • ' in body assert 'link' in body assert renderer.title == "Guide" assert [h["id"] for h in renderer.headings] == ["guide", "part", "part-1"] class TestPages: def test_a_page_is_a_full_document_with_its_canonical_address(self): page = site.layout("docs/a.html", "docs/a.md", "A · paperspec", "

    body

    ") assert page.startswith("") assert ( '' in page ) assert 'data-root="../"' in page assert '' in page assert "A · paperspec" in page assert "

    body

    " in page def test_a_folder_page_is_canonical_at_the_folder(self): page = site.layout( "docs/index.html", None, "Docs", "", base_url="http://localhost:8000/" ) assert 'href="http://localhost:8000/docs/"' in page def test_the_home_page_links_from_the_root(self): page = site.layout("index.html", "README.md", "Home", "") assert 'data-root=""' in page assert 'paperspec' in page assert 'href="https://paperspec.scient.ing/"' in page def test_the_not_found_page_links_from_the_site_root(self): page = site.layout("404.html", None, "Not found", "") assert 'data-root="/"' in page assert 'href="/site.css"' in page def test_a_source_page_links_to_its_markdown_and_the_repository(self): page = site.layout("docs/a.html", "docs/a.md", "A", "", source="docs/a.md") assert f"{site.REPO}/src/branch/main/docs/a.md" in page assert 'raw' in page def test_titles_and_sources_are_escaped(self): page = site.layout("a.html", None, "A & c", "", source="x&y.md") assert "A <b> & c" in page assert "x&y.md" in page def test_the_sidebar_marks_the_current_page(self): nav = site.nav_html("docs/faq.html", "docs/faq.md") assert nav.count('aria-current="page"') == 1 assert 'FAQ' in nav assert 'Overview' in nav assert "

    Specification

    " in nav def test_the_sidebar_of_a_listing_marks_nothing(self): assert "aria-current" not in site.nav_html("docs/index.html", None) def test_the_vocabulary_page_is_marked_in_the_sidebar(self): nav = site.nav_html("vocab/index.html", "vocab") assert 'Vocabulary' in nav def test_the_specification_menu_lists_every_chapter(self): entries = site.spec_nav() assert entries[0] == ("spec/README.md", "Contents") chapters = sorted(p.name for p in (ROOT / "spec").glob("[0-9][0-9]-*.md")) assert [e[0] for e in entries[1:]] == ["spec/" + c for c in chapters] assert all(label for _, label in entries) class MiniSite: """A small checkout the site builder can work on.""" def __init__(self, root): self.root = root self.write("CHANGELOG.md", "# Changelog\n\n## 2.3.4\n\n- change\n") self.write( "README.md", "# Home\n\nSee [guide](docs/guide.md#part) and [data](data/x.json).\n", ) self.write("docs/guide.md", GUIDE) self.write("docs/notitle.md", "no heading here\n") self.write("spec/README.md", "# Spec\n") self.write("spec/01-first.md", "# First chapter\n") self.write("spec/notes.md", "# Not a chapter\n") self.write("data/x.json", '{"a":1}\n') self.write("assets/logo.svg", "") self.write(".secret", "hidden") self.write(".DS_Store", "junk") self.write("node_modules/dep/index.md", "# skipped\n") self.write("_site/old.html", "old") self.write("sub.egg-info/PKG", "x") self.write(".well-known/security.txt", "contact") self.write(".hidden/inside.md", "# hidden\n") self.write( "context/scienting-1.jsonld", json.dumps( { "@context": { "@version": 1.1, "sct": "https://paperspec.scient.ing/vocab#", "as": "https://www.w3.org/ns/activitystreams#", "plain": "sct:plain", "linked": {"@id": "sct:linked", "@type": "@id"}, "blob": {"@id": "sct:blob", "@type": "@json"}, "many": {"@id": "sct:many", "@container": "@set"}, "foreign": "as:foreign", } } ), ) pathlib.Path(self.root / "link.md").symlink_to(self.root / "README.md") def write(self, rel, text): path = self.root / rel path.parent.mkdir(parents=True, exist_ok=True) path.write_text(text, encoding="utf-8") @pytest.fixture def mini(tmp_path, monkeypatch): checkout = tmp_path / "checkout" checkout.mkdir() MiniSite(checkout) monkeypatch.setattr(site, "ROOT", str(checkout)) return checkout class TestBuildMini: def build(self, tmp_path, **kwargs): out = tmp_path / "out" count = site.build(str(out), **kwargs) return out, count def test_every_markdown_file_gets_a_page_and_is_counted(self, mini, tmp_path): out, count = self.build(tmp_path) pages = { "index.html", "docs/guide.html", "docs/notitle.html", "spec/index.html", "spec/01-first.html", "spec/notes.html", "CHANGELOG.html", } assert count == len(pages) for page in pages: assert (out / page).is_file() def test_every_file_is_copied_to_its_own_path(self, mini, tmp_path): out, _ = self.build(tmp_path) assert (out / "data" / "x.json").read_text() == '{"a":1}\n' assert (out / "assets" / "logo.svg").is_file() assert (out / "docs" / "guide.md").read_text() == GUIDE assert (out / ".well-known" / "security.txt").is_file() @pytest.mark.parametrize( "path", [ ".secret", ".DS_Store", "node_modules", "_site", "sub.egg-info", ".hidden", "link.md", "link.html", ], ) def test_hidden_generated_and_linked_files_are_left_out(self, mini, tmp_path, path): out, _ = self.build(tmp_path) assert not (out / path).exists() def test_the_output_folder_inside_the_checkout_is_not_copied_into_itself( self, mini ): out = mini / "public" out.mkdir() (out / "stale.html").write_text("old") site.build(str(out)) assert not (out / "public").exists() def test_an_output_folder_inside_the_checkout_is_emptied_first(self, mini): out = mini / "public" out.mkdir() (out / "stale.html").write_text("old") site.build(str(out)) assert not (out / "stale.html").exists() assert (out / "index.html").is_file() def test_links_between_markdown_files_point_at_pages(self, mini, tmp_path): out, _ = self.build(tmp_path) home = (out / "index.html").read_text() assert 'href="docs/guide.html#part"' in home assert 'href="data/x.json"' in home def test_the_title_comes_from_the_first_heading(self, mini, tmp_path): out, _ = self.build(tmp_path) assert "paperspec · Home" in (out / "index.html").read_text() assert ( "Guide · paperspec" in (out / "docs/guide.html").read_text() ) assert ( "docs/notitle.md · paperspec" in (out / "docs/notitle.html").read_text() ) def test_the_version_is_the_changelogs_first_heading(self, mini, tmp_path): out, _ = self.build(tmp_path) assert '2.3.4' in (out / "index.html").read_text() def test_a_changelog_without_a_heading_is_unreleased(self, mini): (mini / "CHANGELOG.md").write_text("nothing yet\n") assert site.version() == "unreleased" def test_a_folder_with_a_readme_is_its_index_and_others_get_a_listing( self, mini, tmp_path ): out, _ = self.build(tmp_path) assert '

    Spec

    ' in (out / "spec" / "index.html").read_text() listing = (out / "data" / "index.html").read_text() assert "

    data/

    " in listing assert 'x.json' in listing assert "
    " in listing assert '../' in listing def test_a_listing_names_folders_and_hides_pages_rendered_from_markdown( self, mini, tmp_path ): out, _ = self.build(tmp_path) listing = (out / "docs" / "index.html").read_text() assert 'guide.md' in listing assert "guide.html" not in listing.split("")[1] top = (out / "index.html").read_text() assert '

    Home

    ' in top def test_the_root_listing_is_not_needed_when_a_readme_exists(self, mini, tmp_path): out, _ = self.build(tmp_path) assert '

    Home

    ' in (out / "index.html").read_text() assert '' not in (out / "index.html").read_text() def test_a_root_without_a_readme_gets_a_listing_named_for_the_site( self, mini, tmp_path ): (mini / "README.md").unlink() out, _ = self.build(tmp_path) listing = (out / "index.html").read_text() assert "

    paperspec/

    " in listing assert '
    ' not in listing def test_the_vocabulary_page_lists_each_term_of_the_namespace(self, mini, tmp_path): out, _ = self.build(tmp_path) page = (out / "vocab" / "index.html").read_text() assert '
    ' in page assert "https://paperspec.scient.ing/vocab#plain" in page assert "an IRI" in page assert "a JSON literal, kept intact" in page assert "a set" in page assert 'id="foreign"' not in page assert 'id="sct"' not in page def test_the_search_index_lists_pages_headings_and_the_vocabulary( self, mini, tmp_path ): out, _ = self.build(tmp_path) index = json.loads((out / "search.json").read_text()) assert [e["url"] for e in index] == sorted(e["url"] for e in index) guide = next(e for e in index if e["url"] == "docs/guide.html") assert guide["title"] == "Guide" assert {"text": "Part", "id": "part"} in guide["headings"] assert {"text": "Guide", "id": "guide"} not in guide["headings"] assert {"title": "Vocabulary", "url": "vocab/", "headings": []} in index assert any(e["title"] == "docs/notitle.md" for e in index) def test_it_writes_the_stylesheet_the_script_and_the_not_found_page( self, mini, tmp_path ): out, _ = self.build(tmp_path) assert (out / "site.css").read_text() == site.CSS assert (out / "search.js").read_text() == site.SEARCH_JS missing = (out / "404.html").read_text() assert "

    Not found

    " in missing assert f'href="{site.BASE_URL}/"' in missing def test_the_base_url_goes_into_every_canonical_link(self, mini, tmp_path): out, _ = self.build(tmp_path, base_url="http://localhost:8000") for page in out.rglob("*.html"): text = page.read_text() if page.name == "404.html" or '
    8 B
    plain