Merge issue-163-docs-faq-roots: Canonicalize docs and FAQ root URLs (#163)

Author: alexeygrigorev

content/docs_projection.py

@@ -337,7 +337,7 @@ def docs_children(parent_path: str | None) -> tuple[dict[str, Any], ...]:
 
 
 def docs_breadcrumbs(page: Mapping[str, Any]) -> tuple[dict[str, str], ...]:
-    result: list[dict[str, str]] = [{"title": "Documentation", "public_path": "/docs"}]
+    result: list[dict[str, str]] = [{"title": "Documentation", "public_path": DOCS_ROOT_PATH}]
     chain: list[dict[str, Any]] = []
     current = page
     by_path = {item["public_path"]: item for item in docs_projection()["pages"]}

content/public_data.py

@@ -739,9 +739,9 @@ def public_paths() -> tuple[str, ...]:
         "/events",
         "/courses",
         "/wiki",
-        "/docs",
+        "/docs/",
         "/docs/courses/ai-dev-tools-zoomcamp/getting-started/",
-        "/faq",
+        "/faq/",
         "/faq/ai-dev-tools-zoomcamp.html",
         "/slack",
         "/courses/ai-dev-tools-zoomcamp/cohorts/ai-dev-tools-2026",

content/public_views.py

@@ -879,14 +879,14 @@ def _section_records(section: str) -> tuple[tuple[str, str], ...]:
             ("/slack", ""),
         ),
         "docs": (
-            ("/docs", ""),
+            ("/docs/", ""),
             ("/docs/courses/ai-dev-tools-zoomcamp/getting-started/", ""),
         ),
     }
     if section in static_sections:
         return static_sections[section]
     if section == "faq":
-        return (("/faq", ""),) + tuple((course["public_path"], "") for course in faq_courses())
+        return (("/faq/", ""),) + tuple((course["public_path"], "") for course in faq_courses())
     if section == "blog":
         return (("/blog", ""),) + tuple(
             (record["public_path"], record["published"][:10]) for record in projection["articles"]

content/review_views.py

@@ -192,7 +192,7 @@ def docs_home(request: HttpRequest) -> HttpResponse:
     return _render(
         request,
         "review/docs_home.html",
-        path="/docs",
+        path="/docs/",
         title="Documentation — DataTalks.Club",
         description=document.get("description")
         or "Guides for DataTalks.Club courses and community learning.",
@@ -275,7 +275,7 @@ def faq_home(request: HttpRequest) -> HttpResponse:
     return _render(
         request,
         "review/faq_home.html",
-        path="/faq",
+        path="/faq/",
         title="Frequently Asked Questions — DataTalks.Club",
         description="Answers to common questions about DataTalks.Club courses.",
         context={
@@ -339,7 +339,7 @@ def _faq_structured_data(course: dict[str, Any]) -> str:
                     "@type": "ListItem",
                     "position": 2,
                     "name": "FAQ",
-                    "item": _canonical("/faq"),
+                    "item": _canonical("/faq/"),
                 },
                 {
                     "@type": "ListItem",

content/tests/test_docs_projection.py

@@ -32,9 +32,11 @@ def test_projection_is_complete_and_pinned(self) -> None:
         self.assertEqual(page["parent_path"], "/docs/courses/ai-dev-tools-zoomcamp/")
 
     def test_docs_home_and_detail_emit_source_content_and_canonicals(self) -> None:
-        home = self.client.get("/docs")
+        home = self.client.get("/docs/")
         self.assertEqual(home.status_code, 200)
-        self.assertContains(home, '<link rel="canonical" href="https://datatalks.club/docs">')
+        self.assertNotIn("Location", home.headers)
+        self.assertContains(home, '<link rel="canonical" href="https://datatalks.club/docs/">')
+        self.assertContains(home, '<meta property="og:url" content="https://datatalks.club/docs/">')
         self.assertContains(home, "DataTalks.Club Zoomcamps Notes and Resources")
         self.assertContains(home, "/docs/courses/")
 
@@ -55,8 +57,6 @@ def test_docs_home_and_detail_emit_source_content_and_canonicals(self) -> None:
     def test_every_projected_page_is_a_trailing_slash_public_page(self) -> None:
         for page in docs_projection()["pages"]:
             public_path = page["public_path"]
-            if public_path == DOCS_ROOT_PATH:
-                public_path = "/docs"
             with self.subTest(public_path=public_path):
                 response = self.client.get(public_path)
                 self.assertEqual(response.status_code, 200)
@@ -72,7 +72,7 @@ def test_navigation_breadcrumbs_follow_source_hierarchy(self) -> None:
         self.assertEqual(
             [(item["title"], item["public_path"]) for item in breadcrumbs],
             [
-                ("Documentation", "/docs"),
+                ("Documentation", "/docs/"),
                 ("General", "/docs/general/"),
                 ("Community Guidelines", "/docs/general/guidelines/"),
             ],

content/tests/test_faq.py

@@ -21,8 +21,13 @@ def test_projection_has_the_pinned_inventory_and_stable_question_ids(self) -> No
         )
 
     def test_faq_hub_lists_every_course(self) -> None:
-        response = self.client.get("/faq")
+        response = self.client.get("/faq/")
         self.assertEqual(response.status_code, 200)
+        self.assertNotIn("Location", response.headers)
+        self.assertContains(response, '<link rel="canonical" href="https://datatalks.club/faq/">')
+        self.assertContains(
+            response, '<meta property="og:url" content="https://datatalks.club/faq/">'
+        )
         for course in faq_courses():
             self.assertContains(response, course["name"])
             self.assertContains(response, f'href="{course["public_path"]}"')

content/tests/test_public_routes_and_seo.py

@@ -17,6 +17,69 @@
 class PublicRouteAndSeoTests(TestCase):
     maxDiff = None
 
+    def test_docs_and_faq_roots_preserve_trailing_slash_contract(self) -> None:
+        roots = (("/docs/", "/docs"), ("/faq/", "/faq"))
+        query = "utm_source=oncall%2Btest&x=a%2Fb&blank="
+        canonical_inventory = set(public_paths())
+
+        for final_path, alias_path in roots:
+            with self.subTest(final_path=final_path):
+                self.assertIn(final_path, canonical_inventory)
+                self.assertNotIn(alias_path, canonical_inventory)
+
+                final = self.client.get(f"{final_path}?{query}", follow=False)
+                self.assertEqual(final.status_code, 200)
+                self.assertNotIn("Location", final.headers)
+                self.assertEqual(final.headers["X-Robots-Tag"], "noindex, nofollow")
+                self.assertContains(
+                    final,
+                    f'<link rel="canonical" href="https://datatalks.club{final_path}">',
+                    count=1,
+                )
+                self.assertContains(
+                    final,
+                    f'<meta property="og:url" content="https://datatalks.club{final_path}">',
+                    count=1,
+                )
+                self.assertNotRegex(
+                    final.content.decode(), rf'href="https://datatalks.club{alias_path}(?:"|[?#])'
+                )
+                self.assertNotRegex(final.content.decode(), rf'href="{alias_path}(?:"|[?#])')
+                self.assertEqual(self.client.head(final_path).status_code, 200)
+                self.assertEqual(self.client.post(final_path).status_code, 405)
+
+                alias = self.client.get(f"{alias_path}?{query}", follow=False)
+                self.assertEqual(alias.status_code, 301)
+                self.assertEqual(alias.headers["Location"], f"{final_path}?{query}")
+                self.assertEqual(alias.headers["X-Robots-Tag"], "noindex, nofollow")
+                head = self.client.head(f"{alias_path}?{query}", follow=False)
+                self.assertEqual(head.status_code, 301)
+                self.assertEqual(head.headers["Location"], f"{final_path}?{query}")
+                self.assertEqual(self.client.post(alias_path).status_code, 405)
+
+        faq_detail = self.client.get("/faq/ai-dev-tools-zoomcamp.html")
+        match = re.search(
+            r'<script type="application/ld\+json">\s*(.*?)\s*</script>',
+            faq_detail.content.decode(),
+            re.DOTALL,
+        )
+        if match is None:
+            self.fail("FAQ detail does not emit JSON-LD")
+        graph = json.loads(match.group(1))["@graph"]
+        breadcrumb = next(item for item in graph if item["@type"] == "BreadcrumbList")
+        self.assertEqual(breadcrumb["itemListElement"][1]["item"], "https://datatalks.club/faq/")
+
+        for section, root in (("docs", "/docs/"), ("faq", "/faq/")):
+            with self.subTest(section=section):
+                response = self.client.get(f"/sitemaps/{section}.xml")
+                self.assertEqual(response.status_code, 200)
+                document = ElementTree.fromstring(response.content)
+                locations = [
+                    node.text or "" for node in document.findall("s:url/s:loc", SITEMAP_NAMESPACE)
+                ]
+                self.assertEqual(locations.count(f"https://datatalks.club{root}"), 1)
+                self.assertNotIn(f"https://datatalks.club{root.rstrip('/')}", locations)
+
     def test_explicit_hub_redirects_are_permanent_one_hop_and_query_preserving(self) -> None:
         redirects = {
             "/articles.html": "/blog",

playwright_tests/test_accessibility.py

@@ -234,8 +234,8 @@ def accessibility_environment() -> AccessibilityEnvironment:
         "events": Surface("/events"),
         "courses": Surface("/courses"),
         "wiki": Surface("/wiki"),
-        "docs": Surface("/docs"),
-        "faq": Surface("/faq"),
+        "docs": Surface("/docs/"),
+        "faq": Surface("/faq/"),
         "slack": Surface("/slack"),
         "article": Surface(article["public_path"]),
         "podcast-detail": Surface(podcast["public_path"]),

playwright_tests/test_foundation_smoke.py

@@ -3,6 +3,7 @@
 import pytest
 from playwright.sync_api import Browser, Page, ViewportSize, expect
 
+from content.docs_projection import docs_projection
 from content.public_data import public_projection
 
 pytestmark = [pytest.mark.core, pytest.mark.django_db(transaction=True)]
@@ -112,6 +113,68 @@ def test_public_home_and_hubs(
             )
 
 
+@pytest.mark.core
+@pytest.mark.parametrize(
+    "viewport",
+    [{"width": 1280, "height": 800}, {"width": 390, "height": 844}],
+)
+def test_docs_and_faq_root_trailing_slash_browser_contract(
+    page: Page,
+    live_server,
+    viewport: ViewportSize,
+) -> None:
+    page.set_viewport_size(viewport)
+    origin = live_server.url
+    query = "utm_source=oncall%2Btest&x=a%2Fb&blank="
+
+    for final_path, alias_path, heading in (
+        ("/docs/", "/docs", "DataTalks.Club Zoomcamps Notes and Resources"),
+        ("/faq/", "/faq", "Frequently Asked Questions"),
+    ):
+        alias = page.request.get(f"{origin}{alias_path}?{query}", max_redirects=0)
+        assert alias.status == 301
+        assert alias.headers["location"] == f"{final_path}?{query}"
+        head = page.request.head(f"{origin}{alias_path}?{query}", max_redirects=0)
+        assert head.status == 301
+        assert head.headers["location"] == f"{final_path}?{query}"
+
+        response = page.goto(f"{origin}{final_path}?{query}", wait_until="networkidle")
+        assert response is not None and response.status == 200
+        assert "location" not in response.headers
+        expect(page).to_have_url(f"{origin}{final_path}?{query}")
+        expect(page.get_by_role("heading", name=heading, exact=True)).to_be_visible()
+        expect(page.locator('link[rel="canonical"]')).to_have_attribute(
+            "href", f"https://datatalks.club{final_path}"
+        )
+        expect(page.locator('meta[property="og:url"]')).to_have_attribute(
+            "content", f"https://datatalks.club{final_path}"
+        )
+        expect(page.locator(f'a[href="{final_path}"]')).to_have_count(1)
+        expect(page.locator(f'a[href="{alias_path}"]')).to_have_count(0)
+
+        redirected = page.goto(f"{origin}{alias_path}?{query}", wait_until="networkidle")
+        assert redirected is not None and redirected.status == 200
+        expect(page).to_have_url(f"{origin}{final_path}?{query}")
+
+    docs_detail = page.goto(
+        f"{origin}/docs/courses/ai-dev-tools-zoomcamp/getting-started/",
+        wait_until="networkidle",
+    )
+    assert docs_detail is not None and docs_detail.status == 200
+    assert page.locator('a[href="/docs/"]').count() >= 1
+    docs_asset_path = docs_projection()["assets"][0]["public_path"]
+    docs_asset = page.request.get(f"{origin}{docs_asset_path}")
+    assert docs_asset.status == 200
+
+    faq_detail = page.goto(f"{origin}/faq/ai-dev-tools-zoomcamp.html", wait_until="networkidle")
+    assert faq_detail is not None and faq_detail.status == 200
+    assert page.locator('a[href="/faq/"]').count() >= 1
+    faq_courses = page.request.get(f"{origin}/faq/json/courses.json")
+    assert faq_courses.status == 200
+    faq_course = page.request.get(f"{origin}/faq/json/ai-dev-tools-zoomcamp.json")
+    assert faq_course.status == 200
+
+
 @pytest.mark.core
 @pytest.mark.parametrize(
     ("viewport", "suffix"),

templates/site_base.html

@@ -178,14 +178,14 @@
                                {% endif %}>
                                 Books
                             </a>
-                            <a href="{{ docs_url|default:'/docs' }}"
+                            <a href="{{ docs_url|default:'/docs/' }}"
                                class="app-heading app-link"
                                {% if primary_navigation_current == "docs" %}
                                    aria-current="page"
                                {% endif %}>
                                 Docs
                             </a>
-                            <a href="{{ faq_url|default:'/faq' }}"
+                            <a href="{{ faq_url|default:'/faq/' }}"
                                class="app-heading app-link"
                                {% if primary_navigation_current == "faq" %}
                                    aria-current="page"