Embedding Vyasa Viewers

Embedding Vyasa Viewers

When building frontend applications or static sites that consume compiled Vyasa output, you must handle semantic linking. The vyasac compiler does not hardcode physical file URLs (e.g., /content/mula/18/78.html). Instead, it uses a semantic URN Protocol.

The URN Protocol

In HTML projections generated by Vyasa, hyperlinks to other verses or chapters use the URN as the href:

<a href="urn:vyasa:bg:18:78?view=reading">Read Full Verse</a>

This decouples the content from the hosting platform. The ?view=reading query parameter is an optional Hint indicating which projection the author intends the user to see.

It is the responsibility of the frontend application (the “Viewer”) to intercept these links and route them appropriately.

Handling Links in Dynamic Web Apps (SvelteKit, Next.js, etc.)

In a Single Page Application (SPA), you don’t want the browser to try and navigate to urn:vyasa:... natively. You must intercept the click event globally and push it to your internal router.

Example: Global Click Interceptor

Place this logic in your root layout component (e.g., +layout.svelte in SvelteKit or layout.tsx in Next.js).

document.addEventListener('click', (e) => {
    // Find the closest anchor tag that was clicked
    const link = e.target.closest('a');
    const href = link?.getAttribute('href');

    // Check if it is a semantic Vyasa URN link
    if (href && href.startsWith('urn:vyasa:')) {
        e.preventDefault(); // Stop native browser navigation

        // Parse the URN and any query hints (like ?view=reading)
        const [urn, query] = href.split('?');
        const searchParams = new URLSearchParams(query || '');
        const view = searchParams.get('view') || 'default';

        // Route to your internal viewer page
        // e.g., /read/urn:vyasa:bg:18:78?view=reading
        myAppRouter.push(`/read/${urn}?view=${view}`);
    }
});

Handling Links in Static HTML Sites

If you are just serving a folder of static HTML files generated by vyasac, you can inject a small script into your base HTML layout (reference.html or similar) to rewrite the links on load.

Example: Static Rewriter Script

<script>
  document.addEventListener('DOMContentLoaded', () => {
    document.querySelectorAll('a[href^="urn:vyasa:"]').forEach(link => {
      const href = link.getAttribute('href');
      const [urn, query] = href.split('?');
      const view = new URLSearchParams(query || '').get('view') || 'default';

      // Rewrite the href to point to the static HTML file
      // e.g., reading.html#urn:vyasa:bg:18:78
      link.setAttribute('href', `${view}.html#${urn}`);
    });
  });
</script>

By keeping links strictly semantic during compilation, the exact same .vy content files can be deployed as static sites, native mobile apps, or rich web applications without modification!