@dmthepm/commune 0.1.0

package/lib/markdown.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The markdown processor, assembled once.
+ *
+ * Astro 7 renders markdown with Sätteri and no longer installs the unified
+ * pipeline, so a consumer who wants `[[WikiLinks]]` has to build a processor
+ * and hand it to `markdown.processor`. That is three imports, an option shape
+ * and one ordering rule (the remark plugin turns wikilinks into links; the
+ * rehype plugin then decides which links are external) — all of it engine
+ * knowledge, none of it a decision a wiki's author should have to re-derive.
+ * This function is that assembly, so `astro.config.mjs` reads as one line.
+ *
+ * `site` is a parameter and not a constant because the engine has no host of
+ * its own: what counts as an external link is decided against the consumer's
+ * own origin, which lives once in their `defineConfig({ site })`.
+ */
+import type { GraphOptions } from './lib/graph.ts';
+export interface CommuneMarkdownOptions extends GraphOptions {
+    /** The site's own origin, exactly as `astro.config.mjs` declares `site`. */
+    site?: string | URL;
+    /**
+     * The project root, for resolving `[[WikiLinks]]` against its content tree.
+     *
+     * Inherited from `GraphOptions`, and almost never worth passing: it
+     * defaults to `process.cwd()`, which is also the default Astro resolves
+     * `root` to. Pass it when the build runs from somewhere other than the
+     * project directory — the same case `astro build --root` exists for.
+     */
+    root?: string;
+}
+export declare function communeMarkdown({ site, root }?: CommuneMarkdownOptions): import("@astrojs/markdown-remark").MarkdownProcessor<import("@astrojs/markdown-remark").UnifiedResolvedOptions>;

package/lib/markdown.js

@@ -0,0 +1,24 @@
+/**
+ * The markdown processor, assembled once.
+ *
+ * Astro 7 renders markdown with Sätteri and no longer installs the unified
+ * pipeline, so a consumer who wants `[[WikiLinks]]` has to build a processor
+ * and hand it to `markdown.processor`. That is three imports, an option shape
+ * and one ordering rule (the remark plugin turns wikilinks into links; the
+ * rehype plugin then decides which links are external) — all of it engine
+ * knowledge, none of it a decision a wiki's author should have to re-derive.
+ * This function is that assembly, so `astro.config.mjs` reads as one line.
+ *
+ * `site` is a parameter and not a constant because the engine has no host of
+ * its own: what counts as an external link is decided against the consumer's
+ * own origin, which lives once in their `defineConfig({ site })`.
+ */
+import { unified } from '@astrojs/markdown-remark';
+import remarkWikiLinks from "./remark-wikilinks.js";
+import rehypeExternalLinks from "./rehype-external-links.js";
+export function communeMarkdown({ site, root } = {}) {
+    return unified({
+        remarkPlugins: [[remarkWikiLinks, { root }]],
+        rehypePlugins: [[rehypeExternalLinks, { site }]],
+    });
+}

package/lib/rehype-external-links.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Rehype plugin to open every external link in a new tab.
+ *
+ * The design system marks `a[target="_blank"]` with an arrow, so setting the
+ * attribute here is what makes that marker automatic for plain markdown links.
+ */
+import type { Root } from 'hast';
+export interface ExternalLinksOptions {
+    /** The site's own origin, exactly as `astro.config.mjs` declares `site`. */
+    site?: string | URL;
+}
+/**
+ * Rehype plugin function
+ */
+export default function rehypeExternalLinks({ site }?: ExternalLinksOptions): (tree: Root) => void;

package/lib/rehype-external-links.js

@@ -0,0 +1,46 @@
+/**
+ * Rehype plugin to open every external link in a new tab.
+ *
+ * The design system marks `a[target="_blank"]` with an arrow, so setting the
+ * attribute here is what makes that marker automatic for plain markdown links.
+ */
+import { visit } from 'unist-util-visit';
+/**
+ * Rehype plugin function
+ */
+export default function rehypeExternalLinks({ site } = {}) {
+    // A link is internal because it points at the site's own host, and the
+    // engine has no host of its own: it comes from the Astro `site` config.
+    // Without one, nothing can be recognised as internal by hostname — only
+    // relative links stay untouched.
+    const siteHost = site ? new URL(site).hostname : null;
+    return function transformer(tree) {
+        visit(tree, 'element', (node) => {
+            if (node.tagName !== 'a')
+                return;
+            // A link that already declares `target` was written by hand — raw
+            // HTML in a note, or a component — and owns its own `rel`.
+            // Overwriting it would drop attributes its author chose.
+            if (node.properties?.target !== undefined)
+                return;
+            const href = node.properties?.href;
+            if (typeof href !== 'string')
+                return;
+            // Wikilinks and internal links are relative, so they have no
+            // protocol, never match here, and are left alone.
+            if (!href.startsWith('http://') && !href.startsWith('https://'))
+                return;
+            let hostname;
+            try {
+                hostname = new URL(href).hostname;
+            }
+            catch {
+                return;
+            }
+            if (hostname === siteHost)
+                return;
+            node.properties.target = '_blank';
+            node.properties.rel = ['noopener', 'noreferrer'];
+        });
+    };
+}

package/lib/remark-wikilinks.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Remark plugin to transform WikiLinks [[Note Title]] into proper markdown links.
+ *
+ * Transforms:
+ *   [[Atomic Notes]] → [Atomic Notes](/notes/atomic-notes/)
+ *   [[Note Title|Display Text]] → [Display Text](/notes/note-title/)
+ *
+ * This runs at build time during markdown compilation, before HTML generation.
+ * Which content exists, and the URL each piece lives at, is decided by the
+ * graph core in `src/lib/graph.ts` — not here.
+ */
+import type { Root } from 'mdast';
+import { type GraphOptions } from './lib/graph.ts';
+export type WikiLinksOptions = GraphOptions;
+/**
+ * Remark plugin function.
+ *
+ * Takes the project root rather than assuming one, because the plugin resolves
+ * links against the content tree of whichever project is being built — which,
+ * once this is a package in somebody else's `node_modules`, is not the
+ * directory this file lives in. Omitting it falls back to `process.cwd()`,
+ * which is also Astro's own default for `root`, so a consumer who does not
+ * pass one gets the project they ran `astro build` in.
+ */
+export default function remarkWikiLinks({ root }?: WikiLinksOptions): (tree: Root) => Promise<void>;

package/lib/remark-wikilinks.js

@@ -0,0 +1,108 @@
+/**
+ * Remark plugin to transform WikiLinks [[Note Title]] into proper markdown links.
+ *
+ * Transforms:
+ *   [[Atomic Notes]] → [Atomic Notes](/notes/atomic-notes/)
+ *   [[Note Title|Display Text]] → [Display Text](/notes/note-title/)
+ *
+ * This runs at build time during markdown compilation, before HTML generation.
+ * Which content exists, and the URL each piece lives at, is decided by the
+ * graph core in `src/lib/graph.ts` — not here.
+ */
+import { visit } from 'unist-util-visit';
+import { getLinkLookup } from "./lib/graph.js";
+/**
+ * Remark plugin function.
+ *
+ * Takes the project root rather than assuming one, because the plugin resolves
+ * links against the content tree of whichever project is being built — which,
+ * once this is a package in somebody else's `node_modules`, is not the
+ * directory this file lives in. Omitting it falls back to `process.cwd()`,
+ * which is also Astro's own default for `root`, so a consumer who does not
+ * pass one gets the project they ran `astro build` in.
+ */
+export default function remarkWikiLinks({ root } = {}) {
+    return async function transformer(tree) {
+        const lookup = await getLinkLookup({ root });
+        visit(tree, 'text', (node, index, parent) => {
+            if (!parent || index === undefined)
+                return;
+            const text = node.value;
+            const wikiLinkRegex = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+            // Check if this text node contains WikiLinks
+            if (!wikiLinkRegex.test(text))
+                return;
+            // Reset regex
+            wikiLinkRegex.lastIndex = 0;
+            const newNodes = [];
+            let lastIndex = 0;
+            let match;
+            while ((match = wikiLinkRegex.exec(text)) !== null) {
+                const [fullMatch, linkText, displayText] = match;
+                const startIndex = match.index;
+                // Add text before the WikiLink
+                if (startIndex > lastIndex) {
+                    newNodes.push({
+                        type: 'text',
+                        value: text.slice(lastIndex, startIndex),
+                    });
+                }
+                // Resolve WikiLink to URL path
+                const trimmedLinkText = linkText.trim();
+                const lookupKey = trimmedLinkText.toLowerCase();
+                const resolved = lookup.get(lookupKey);
+                if (resolved) {
+                    // Create a proper link node with correct URL for collection
+                    // Add data-collection attribute to identify research links for styling
+                    const linkNode = {
+                        type: 'link',
+                        url: resolved.urlPath,
+                        children: [
+                            {
+                                type: 'text',
+                                value: displayText?.trim() || trimmedLinkText,
+                            },
+                        ],
+                    };
+                    // Add data attribute for research links (will be used for new tab behavior)
+                    if (resolved.collection === 'research') {
+                        linkNode.data = {
+                            hProperties: {
+                                'data-collection': 'research',
+                                'class': 'wikilink research-link'
+                            }
+                        };
+                    }
+                    else {
+                        linkNode.data = {
+                            hProperties: {
+                                'class': 'wikilink'
+                            }
+                        };
+                    }
+                    newNodes.push(linkNode);
+                }
+                else {
+                    // Leave unresolved WikiLinks as plain text (without brackets)
+                    // These are notes that don't exist yet in the public wiki
+                    newNodes.push({
+                        type: 'text',
+                        value: displayText?.trim() || trimmedLinkText,
+                    });
+                }
+                lastIndex = startIndex + fullMatch.length;
+            }
+            // Add remaining text
+            if (lastIndex < text.length) {
+                newNodes.push({
+                    type: 'text',
+                    value: text.slice(lastIndex),
+                });
+            }
+            // Replace the text node with our transformed nodes
+            if (newNodes.length > 0) {
+                parent.children.splice(index, 1, ...newNodes);
+            }
+        });
+    };
+}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@dmthepm/commune",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "An Astro wiki engine with WikiLinks, sliding panes, backlinks and static search, plus a commune CLI that queries the content graph and checks links",
+  "license": "MIT",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "withastro",
+    "wiki",
+    "wikilinks",
+    "backlinks"
+  ],
+  "bin": {
+    "commune": "bin/commune.mjs"
+  },
+  "exports": {
+    "./graph": {
+      "types": "./lib/lib/graph.d.ts",
+      "default": "./lib/lib/graph.js"
+    },
+    "./astro": {
+      "types": "./lib/integration.d.ts",
+      "default": "./lib/integration.js"
+    },
+    "./markdown": {
+      "types": "./lib/markdown.d.ts",
+      "default": "./lib/markdown.js"
+    },
+    "./remark": {
+      "types": "./lib/remark-wikilinks.d.ts",
+      "default": "./lib/remark-wikilinks.js"
+    },
+    "./rehype": {
+      "types": "./lib/rehype-external-links.d.ts",
+      "default": "./lib/rehype-external-links.js"
+    },
+    "./components/*": "./src/components/*",
+    "./styles/*": "./src/styles/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "src/components",
+    "src/styles",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmthepm/commune-wiki.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dmthepm/commune-wiki/issues"
+  },
+  "homepage": "https://github.com/dmthepm/commune-wiki#readme",
+  "scripts": {
+    "build:lib": "tsc -p tsconfig.build.json",
+    "prepare": "pnpm build:lib",
+    "pretest": "pnpm build:lib",
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "pnpm build:lib && astro build && node bin/commune.mjs gate",
+    "test": "node --test \"tests/**/*.test.mjs\"",
+    "test:consumer": "pnpm --dir tests/fixtures/consumer install && pnpm --dir tests/fixtures/consumer build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "peerDependencies": {
+    "@astrojs/markdown-remark": "^7.3.0",
+    "astro": "^7.0.0"
+  },
+  "dependencies": {
+    "github-slugger": "^2.0.0",
+    "globby": "^14.0.0",
+    "gray-matter": "^4.0.3",
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.0",
+    "@astrojs/markdown-remark": "^7.3.0",
+    "@astrojs/sitemap": "^3.7.4",
+    "@tailwindcss/typography": "^0.5.10",
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.20.1",
+    "astro": "^7.2.10",
+    "autoprefixer": "^10.4.16",
+    "puppeteer": "^24.25.0",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/components/Backlinks.astro

@@ -0,0 +1,17 @@
+---
+export interface Props { slug: string; title?: string; hideCount?: boolean; }
+const { slug, hideCount = false } = Astro.props;
+---
+<aside class="backlinks" data-backlinks-for={slug} data-hide-count={hideCount ? 'true' : undefined}>
+  <h4>Links to this note</h4>
+  <ul class="backlinks-list"></ul>
+</aside>
+
+<style>
+  .backlinks{margin-top:3rem;padding-top:1.2rem;border-top:1px solid var(--c-border)}
+  .backlinks.hidden{display:none}
+  .backlinks h4{font-size:.85rem;color:var(--c-text-muted);margin:0 0 .8rem;font-weight:500}
+  .backlinks li{margin:.4rem 0;font-size:.9rem}
+  .backlinks a{opacity:.85}
+  .backlinks a:hover{opacity:1}
+</style>

package/src/components/BacklinksScript.astro

@@ -0,0 +1,117 @@
+<script is:inline>
+// === BACKLINKS INITIALIZATION ===
+// Handles dynamic backlinks loading for both static and dynamically loaded panes
+
+(function() {
+  let backlinksData = null;
+
+  async function initializeBacklinks(scope = document) {
+    try {
+      // Fetch backlinks data if not already loaded
+      if (!backlinksData) {
+        const res = await fetch('/backlinks.json');
+        if (res.ok) {
+          backlinksData = await res.json();
+        } else {
+          console.warn('Failed to load backlinks.json');
+          return;
+        }
+      }
+
+      // Find all backlinks sections within the scope
+      const backlinksSections = scope.querySelectorAll('.backlinks');
+
+      backlinksSections.forEach(section => {
+        const slug = section.dataset.backlinksFor;
+        if (!slug) return;
+
+        const list = section.querySelector('.backlinks-list');
+        if (!list) return;
+
+        // Get backlinks for this slug
+        const here = slug.endsWith('/') ? slug : slug + '/';
+        const rec = backlinksData?.[here];
+        const items = rec?.inbound ?? [];
+
+        if (!items.length) {
+          // Hide the entire section if no backlinks
+          section.classList.add('hidden');
+          return;
+        }
+
+        // Show the section and populate links
+        section.classList.remove('hidden');
+
+        // Update heading with count (unless hideCount attribute is present)
+        const heading = section.querySelector('h4');
+        const hideCount = section.hasAttribute('data-hide-count');
+        if (heading && !hideCount) {
+          const count = items.length;
+          const linkText = count === 1 ? 'link' : 'links';
+          heading.textContent = `${count} ${linkText} to this note`;
+        }
+
+        const titleFor = (u) => {
+          const note = backlinksData[u];
+          return note?.title || u.split('/').filter(Boolean).pop()?.replace(/-/g,' ');
+        };
+
+        // Render links and then add stars as separate clickable elements
+        list.innerHTML = items.map(s => `<li><a href="${s}">${titleFor(s)}</a></li>`).join('');
+
+        // Add stars to starred notes
+        list.querySelectorAll('li').forEach((li, index) => {
+          const url = items[index];
+          const note = backlinksData[url];
+
+          if (note?.isStarred && !li.querySelector('.star-indicator-inline')) {
+            const link = li.querySelector('a');
+            if (link) {
+              const star = document.createElement('span');
+              star.className = 'star-indicator-inline';
+              star.textContent = ' ⭐';
+              star.setAttribute('aria-label', 'Top 5% most linked - click to learn more');
+              star.setAttribute('role', 'button');
+              star.setAttribute('tabindex', '0');
+
+              // Click handler to open modal
+              star.addEventListener('click', (e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                if (typeof window.showStarModal === 'function') {
+                  window.showStarModal();
+                }
+              });
+
+              // Keyboard support
+              star.addEventListener('keydown', (e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  if (typeof window.showStarModal === 'function') {
+                    window.showStarModal();
+                  }
+                }
+              });
+
+              link.insertAdjacentElement('afterend', star);
+            }
+          }
+        });
+      });
+    } catch (error) {
+      console.error('Error initializing backlinks:', error);
+    }
+  }
+
+  // Make it globally available for dynamic pane loading
+  window.initializeBacklinks = initializeBacklinks;
+
+  // Auto-initialize on DOM ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => initializeBacklinks());
+  } else {
+    initializeBacklinks();
+  }
+})();
+</script>

package/src/components/Footer.astro

@@ -0,0 +1,35 @@
+---
+// Footer component with "Powered by Commune" link
+---
+<footer class="site-footer">
+  <p>Powered by <a href="/notes/what-is-commune/">Commune</a></p>
+</footer>
+
+<style>
+  .site-footer {
+    margin-top: 3rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--c-border);
+    text-align: center;
+  }
+
+  .site-footer p {
+    margin: 0;
+    font-size: 0.9rem;
+    color: var(--c-text-muted);
+  }
+
+  .site-footer a {
+    color: var(--c-accent);
+    text-decoration: none;
+    border-bottom: 1px solid var(--c-accent);
+    padding-bottom: 1px;
+    transition: all 0.15s ease;
+  }
+
+  .site-footer a:hover {
+    color: var(--c-accent-hover);
+    background: var(--c-accent-soft);
+    border-bottom-color: var(--c-accent-hover);
+  }
+</style>