ColivingLiguria

Apply Now

3 min read

Global Index Routing & PDF Linking

For AI Agents: Read this carefully before attempting to add new index pages, dynamic TSX components, or link to PDFs generated from LaTeX.

The ColivingLiguria Quartz documentation uses a highly customized routing setup. If you ignore these rules, you will encounter double-rendering bugs, hidden index pages, or 404 dead links.

1. Creating Custom TSX Index Pages

Quartz naturally attempts to render a list of files (FolderContent / .page-listing) whenever a user navigates to a folder’s index.md. To override this with a beautiful, custom TSX component without breaking the layout, follow these EXACT steps:

Step A: Build the Component with a CSS Override

Create your component (e.g., MyIndex.tsx) in quartz/components/. To prevent Quartz’s default file list from rendering below your custom component, you MUST inject a <style> block to hide .page-listing:

export default (() => {
    const MyIndex: QuartzComponent = ({ displayClass }: QuartzComponentProps) => {
        return (
            <div class={\`landing-page \${displayClass ?? ""}\`}>
                <style>
                    {\`
                        .page-listing { display: none !important; }
                    \`}
                </style>
                <section class="hero">
                    {/* ... your custom UI ... */}
                </section>
            </div>
        )
    }
    MyIndex.css = style
    return MyIndex
}) satisfies QuartzComponentConstructor

Step B: The componentsLibrary Injection (CRITICAL)

Open quartz.layout.tsx. You must register your new component EXACTLY ONCE inside the componentsLibrary array at the top of the file mapping to the frontmatter string.

// Inside quartz.layout.tsx -> componentsLibrary array:
Component.ConditionalRender({
  component: Component.MyIndex(),
  condition: (page) => page.fileData.frontmatter?.component === "MyIndex",
}),

WARNING

DO NOT inject your component manually into defaultContentPageLayout or defaultListPageLayout. componentsLibrary is already unpacked automatically via the spread operator (...componentsLibrary) inside all layouts. Injecting it manually elsewhere will cause the component to render twice on the screen.

Step C: The Markdown Hook

In your target folder’s index.md (e.g., content/Administration/index.md), attach the component via frontmatter:

---
title: "My Index"
component: "MyIndex"
---

2. Linking to PDFs and Internal Pages

Linking to Internal Markdown Pages

When writing href attributes inside your TSX components to link to other pages, rely on the strict Quartz slugification rules mapped in Internal Linking:

  • Extract the path relative to /content/.
  • Remove .md and index.
  • Replace spaces with hyphens (-).
  • Example: content/Administration/Administration Diary/index.md becomes href="/Administration/Administration-Diary/".

Linking to PDFs (The CL-sync Pipeline)

PDFs are built in the LaTeX submodule (LaTeX_CL) and then copied to Quartz by the ./CL-sync script. They are universally deposited into: Quartz_CL/content/System/Assets/Documents/

  1. Check the CL-sync script (Admin_CL/scripts/CL-sync) to confirm the PDF is actively being copied to Assets/Documents/.
  2. Do NOT hardcode paths if the PDF is critical or frequently accessed.
  3. Instead, add the PDF path to Quartz_CL/quartz/components/config/ConfigLinks.ts to keep a central registry.

Example ConfigLinks.ts registration:

export const ConfigLinks = {
    PDFs: {
        PR_NO_001_Statuto: "/System/Assets/Documents/Grant_Applications/Bando_PIA/PR-NO-001.pdf",
        AD_FI_002_Luna: "/System/Assets/Documents/Administration/2026/February/AD-FI-002.pdf"
    }
};

Example Usage in TSX:

import { ConfigLinks } from "./config/ConfigLinks"
 
// Usage:
<a href={ConfigLinks.PDFs.PR_NO_001_Statuto} target="_blank" class="download-btn">
   Download Document
</a>

By following these protocols, you ensure the routing remains resilient, localized, and devoid of duplicates.

Graph View