feat(projects): render descriptions with Markdown

package.json

@@ -36,6 +36,9 @@
     "jose": "^6.2.8",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "remark-breaks": "^4.0.0",
+    "remark-gfm": "^4.0.1",
     "tus-js-client": "^4.3.1",
     "wouter": "^3.10.0"
   },

src/app/components/Markdown.tsx

@@ -0,0 +1,44 @@
+import MarkdownRenderer, {type Components} from 'react-markdown';
+import remarkBreaks from 'remark-breaks';
+import remarkGfm from 'remark-gfm';
+
+const components: Components = {
+  a({node, href, ...props}) {
+    void node;
+    const external = href?.startsWith('https://') || href?.startsWith('http://');
+    return (
+      <a
+        {...props}
+        href={href}
+        target={external ? '_blank' : undefined}
+        rel={external ? 'noreferrer' : undefined}
+      />
+    );
+  },
+};
+
+const compactElements = ['a', 'strong', 'em', 'del', 'code', 'br'] as const;
+
+export function Markdown({
+  children,
+  compact = false,
+}: {
+  children: string;
+  compact?: boolean;
+}) {
+  return (
+    <div
+      className={compact ? 'markdown markdown--compact' : 'markdown'}
+      title={compact ? children : undefined}
+    >
+      <MarkdownRenderer
+        allowedElements={compact ? compactElements : undefined}
+        components={components}
+        remarkPlugins={[remarkGfm, remarkBreaks]}
+        unwrapDisallowed={compact}
+      >
+        {children}
+      </MarkdownRenderer>
+    </div>
+  );
+}

src/app/components/ProjectCard.tsx

@@ -1,6 +1,7 @@
 import {Link} from 'wouter';
 
 import type {ProjectSummary} from '../../shared/projects';
+import {Markdown} from './Markdown';
 
 export function ProjectCard({
   project,
@@ -29,7 +30,7 @@ export function ProjectCard({
       <h2>
         <Link href={projectLink}>{project.name}</Link>
       </h2>
-      <p title={project.summary}>{project.summary}</p>
+      <Markdown compact>{project.summary}</Markdown>
       <footer>
         <MemberStack members={project.members} />
       </footer>

src/app/components/ProjectForm.tsx

@@ -146,6 +146,9 @@ export function ProjectForm({
           value={summary}
           onChange={(event) => setSummary(event.target.value)}
         />
+        <small className="fieldHint">
+          Markdown supported — add links, headings, lists, tables, and more.
+        </small>
       </label>
       {!project && !claim && (
         <fieldset className="kindPicker">

src/app/routes/ProjectDetailsPage.tsx

@@ -2,6 +2,7 @@ import {useState, type ChangeEvent} from 'react';
 import {Link, useLocation, useParams} from 'wouter';
 
 import {QueryState} from '../components/AppLayout';
+import {Markdown} from '../components/Markdown';
 import {useProjectVideo} from '../queries/videos';
 import {ProjectVideoPanel} from '../video/ProjectVideoPanel';
 import {
@@ -96,7 +97,7 @@ export function ProjectDetailsPage() {
             <article className="projectNarrative">
               <p className="kicker">project summary</p>
               <h2>about this project</h2>
-              <p>{project.data.project.summary}</p>
+              <Markdown>{project.data.project.summary}</Markdown>
               {project.data.project.repository && (
                 <a
                   className="repoLink"

src/app/routes/VotingPage.tsx

@@ -2,6 +2,7 @@ import {useState} from 'react';
 import {Link, useParams} from 'wouter';
 
 import {QueryState} from '../components/AppLayout';
+import {Markdown} from '../components/Markdown';
 import {useVoteMutation, useVoting} from '../queries/administration';
 
 export function VotingPage() {
@@ -80,7 +81,7 @@ export function VotingPage() {
                               <div>
                                 <small>{project.groupName ?? 'Independent'}</small>
                                 <h3>{project.name}</h3>
-                                <p>{project.summary}</p>
+                                <Markdown compact>{project.summary}</Markdown>
                               </div>
                               <footer>
                                 <span>{project.memberNames.join(' · ')}</span>

src/app/styles.css

@@ -78,6 +78,17 @@ input:disabled {
   color: #fff;
   background: var(--blurple);
 }
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
 
 .appFrame {
   display: flex;
@@ -798,11 +809,9 @@ main {
 .projectCard h2 a {
   text-decoration: none;
 }
-.projectCard > p {
+.projectCard > .markdown {
   display: -webkit-box;
   overflow: hidden;
-  margin: 0;
-  color: var(--muted);
   font-size: 0.95rem;
   line-height: 1.55;
   -webkit-box-orient: vertical;
@@ -1005,7 +1014,7 @@ main {
   gap: clamp(2rem, 6vw, 5rem);
   padding: clamp(2rem, 5vw, 4rem) 0;
 }
-.projectNarrative h2,
+.projectNarrative > h2,
 .teamPanel h2,
 .mediaSection h2,
 .ballotSection h2,
@@ -1016,11 +1025,99 @@ main {
   line-height: 1.15;
   letter-spacing: -0.035em;
 }
-.projectNarrative > p:not(.kicker) {
+.markdown {
+  overflow-wrap: anywhere;
   color: var(--muted);
   font-size: 1rem;
   line-height: 1.8;
-  white-space: pre-wrap;
+}
+.markdown > :first-child {
+  margin-top: 0;
+}
+.markdown > :last-child {
+  margin-bottom: 0;
+}
+.markdown h1,
+.markdown h2,
+.markdown h3,
+.markdown h4,
+.markdown h5,
+.markdown h6 {
+  margin: 1.5em 0 0.55em;
+  color: var(--ink);
+  font-size: 1.15rem;
+  line-height: 1.3;
+  letter-spacing: -0.015em;
+}
+.markdown p,
+.markdown ul,
+.markdown ol,
+.markdown blockquote,
+.markdown pre,
+.markdown table {
+  margin: 0 0 1rem;
+}
+.markdown ul,
+.markdown ol {
+  padding-left: 1.5rem;
+}
+.markdown li + li {
+  margin-top: 0.3rem;
+}
+.markdown a {
+  color: var(--blurple);
+  font-weight: 500;
+  text-decoration-thickness: 0.08em;
+  text-underline-offset: 0.15em;
+}
+.markdown blockquote {
+  padding-left: 1rem;
+  border-left: 3px solid #d2bfff;
+}
+.markdown blockquote > :last-child {
+  margin-bottom: 0;
+}
+.markdown code {
+  padding: 0.12rem 0.3rem;
+  border-radius: 0.25rem;
+  background: var(--soft);
+  font-size: 0.9em;
+}
+.markdown pre {
+  overflow-x: auto;
+  padding: 1rem;
+  border: 1px solid var(--line);
+  border-radius: 0.5rem;
+  background: var(--soft);
+}
+.markdown pre code {
+  padding: 0;
+  background: transparent;
+}
+.markdown table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+}
+.markdown th,
+.markdown td {
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--line);
+}
+.markdown th {
+  color: var(--ink);
+  background: var(--soft);
+  text-align: left;
+}
+.markdown img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 0.5rem;
+}
+.markdown .contains-task-list {
+  padding-left: 0;
+  list-style: none;
 }
 .repoLink {
   display: inline-block;
@@ -1194,6 +1291,12 @@ main {
   border-radius: 0.5rem;
   background: #fff;
 }
+.fieldHint {
+  display: block;
+  margin-top: 0.45rem;
+  color: var(--muted);
+  font-size: 0.72rem;
+}
 .projectForm input:focus,
 .projectForm textarea:focus,
 .projectForm select:focus,
@@ -1500,10 +1603,12 @@ main {
   margin: 1rem 0 0.5rem;
   font-size: 1.35rem;
 }
-.ballotCard p {
-  margin: 0;
-  color: var(--muted);
+.ballotCard .markdown {
+  display: -webkit-box;
+  overflow: hidden;
   line-height: 1.55;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 6;
 }
 .ballotCard footer {
   display: flex;

test/app/administration.test.tsx

@@ -15,6 +15,26 @@ vi.stubGlobal('fetch', fetchMock);
 afterEach(() => fetchMock.mockReset());
 
 describe('voting and administration journeys', () => {
+  it('renders compact Markdown in voting cards', async () => {
+    fetchMock.mockResolvedValue(
+      json({
+        ...votingFixture,
+        projects: [
+          {
+            ...votingFixture.projects[0],
+            summary: '**Working** details at [the docs](https://example.com).',
+          },
+        ],
+      }),
+    );
+    renderRoute(<VotingPage />, '/years/2026/vote', '/years/:yearId/vote');
+
+    expect((await screen.findByText('Working')).tagName).toBe('STRONG');
+    const link = screen.getByRole('link', {name: 'the docs'});
+    expect(link.closest('.markdown')?.classList.contains('markdown--compact')).toBe(true);
+    expect(link.getAttribute('target')).toBe('_blank');
+  });
+
   it('moves an existing vote to the selected project through the API', async () => {
     fetchMock.mockImplementation(async (_input, init) => {
       if (init?.method === 'PUT') return json({vote: {...vote, projectId: 'project-2'}});

test/app/routes.test.tsx

@@ -7,6 +7,7 @@ import {memoryLocation} from 'wouter/memory-location';
 import {afterEach, describe, expect, it, vi} from 'vitest';
 
 import {AppLayout} from '../../src/app/components/AppLayout';
+import {ProjectCard} from '../../src/app/components/ProjectCard';
 import {ProjectDetailsPage} from '../../src/app/routes/ProjectDetailsPage';
 import {ProjectsPage} from '../../src/app/routes/ProjectsPage';
 import {YearsPage} from '../../src/app/routes/YearsPage';
@@ -435,6 +436,70 @@ describe('clickable project routes', () => {
     });
   });
 
+  it('renders compact Markdown in project cards without exposing block layout', () => {
+    const summary =
+      '# Overview\nFirst line\nSecond line with **detail** and a [link](https://example.com).';
+
+    renderRoute(<ProjectCard project={{...projectFixture, summary}} />, '/');
+
+    const link = screen.getByRole('link', {name: 'link'});
+    const description = link.closest('.markdown');
+    expect(description?.classList.contains('markdown--compact')).toBe(true);
+    expect(description?.getAttribute('title')).toBe(summary);
+    expect(screen.getByText('detail').tagName).toBe('STRONG');
+    expect(screen.queryByRole('heading', {name: 'Overview'})).toBeNull();
+  });
+
+  it('renders project descriptions as GitHub-flavored Markdown', async () => {
+    fetchMock.mockResolvedValue(
+      json({
+        project: {
+          ...projectFixture,
+          summary:
+            'Built with **care**. Visit https://example.com/docs.\nSecond line with [details](#details).\n\nUse <Widget> safely.\n\n- [x] Links work',
+        },
+      }),
+    );
+
+    const rendered = renderRoute(
+      <ProjectDetailsPage />,
+      '/years/2026/projects/project',
+      '/years/:yearId/projects/:projectId',
+    );
+
+    expect((await screen.findByText('care')).tagName).toBe('STRONG');
+    const link = screen.getByRole('link', {name: 'https://example.com/docs'});
+    expect(link.getAttribute('href')).toBe('https://example.com/docs');
+    expect(link.getAttribute('target')).toBe('_blank');
+    expect(link.getAttribute('rel')).toBe('noreferrer');
+    expect(screen.getByRole('link', {name: 'details'}).getAttribute('target')).toBeNull();
+    expect(rendered.container.querySelector('.markdown br')).toBeTruthy();
+    expect(screen.getByText('Use <Widget> safely.')).toBeTruthy();
+    expect((screen.getByRole('checkbox') as HTMLInputElement).checked).toBe(true);
+  });
+
+  it('sanitizes unsafe Markdown URLs and raw HTML', async () => {
+    fetchMock.mockResolvedValue(
+      json({
+        project: {
+          ...projectFixture,
+          summary: '[unsafe](javascript:alert(1))\n\n<img src=x onerror=alert(1)>',
+        },
+      }),
+    );
+
+    const rendered = renderRoute(
+      <ProjectDetailsPage />,
+      '/years/2026/projects/project',
+      '/years/:yearId/projects/:projectId',
+    );
+
+    const link = (await screen.findByText('unsafe')).closest('a');
+    expect(link?.getAttribute('href')).toBe('');
+    expect(rendered.container.querySelector('.markdown img')).toBeNull();
+    expect(screen.getByText('<img src=x onerror=alert(1)>')).toBeTruthy();
+  });
+
   it('renders an idea with no video and exposes the server claim permission', async () => {
     fetchMock.mockResolvedValue(
       json({