The minimalistic document archiving platform.
feat(website): add intent-based docs structure (#1504)
Corentin Thomassetf41920b6a5a9
diff --git a/apps/website/src/content.config.ts b/apps/website/src/content.config.tsindex 18eb45ed..a17249b4 100644--- a/apps/website/src/content.config.ts+++ b/apps/website/src/content.config.ts@@ -22,7 +22,12 @@ const blog = defineCollection({const docs = defineCollection({// IDs are <locale>/<docId>; translations share the same locale-independent docId.- loader: glob({ pattern: '**/*.mdx', base: './src/docs/content' }),+ loader: glob({+ pattern: '**/*.mdx',+ base: './src/docs/content',+ // Preserve index in IDs: Astro's default slugger turns en/index.mdx into en.+ generateId: ({ entry }) => entry.replace(/\.mdx$/, ''),+ }),schema: z.object({title: z.string(),description: z.string(),diff --git a/apps/website/src/docs/README.md b/apps/website/src/docs/README.mdnew file mode 100644index 00000000..69b14d99--- /dev/null+++ b/apps/website/src/docs/README.md@@ -0,0 +1,31 @@+# Documentation structure++Organize documentation by **what the reader wants to do**, not by document format.++## Main navigation++- **Overview**: introduce Papra and route readers to the right category. A regular category, initially containing only Introduction (`/docs`); future introductory pages can cover choosing cloud or self-hosting and first steps.+- **User guide**: use Papra, whether cloud or self-hosted. Document workflows, search, tags, organization membership, and feature usage.+- **Self-hosting**: install, configure, administer, and maintain an instance. Includes deployment methods, OAuth, storage, encryption, ingestion setup, OCR/LLM providers, backups, upgrades, and troubleshooting.+- **Developers**: automate and integrate with Papra. Includes API, SDK, webhooks, CLI reference, recipes, and initially contributor documentation.+- **Concepts**: understand behavior and design choices. Includes original document preservation, deduplication, processing, and deletion/purge lifecycles. Explanations should be useful beyond the contributor audience.++## Placement rules++- Keep tutorials, how-to guides, reference, and explanations distinct where useful, but do not make these document types the top-level navigation.+- Keep reference material near its audience: environment variables under Self-hosting, API endpoints under Developers, search syntax under User guide.+- Give each page one canonical home. Cross-link related pages instead of duplicating them.+- Separate using a feature from enabling it on the server. For example, organization auto-tagging belongs in User guide; configuring its LLM provider belongs in Self-hosting.+- Separate organization permissions (User guide) from platform administration (Self-hosting).+- Avoid catch-all categories such as “Guides” and “Resources”. Changelog, community, support, and security can be secondary links.+- Add sidebar sections when there is content for them. Do not publish empty sections or links to unwritten pages. Contributing can become a category if it grows enough to need its own navigation.++## Implementation and migration++`docs.navigations.ts` defines category membership and sidebar order. Membership, not the document's directory, determines its active category and pagination.++Content lives in `content/<locale>/`; English is the required source. The landing document is `content/<locale>/index.mdx`, with logical ID `index`. It uses the same renderer, navigation, translation fallback, and editing actions as other documents. URL helpers and static paths map it to `/<locale>/docs`, never `/docs/index`; its Markdown export is `/<locale>/docs.md`. Landing cards use the reusable `DocLinkCard.astro` component inside MDX.++Keep existing documents and URLs in place until migration is explicitly undertaken. The initial category introductions establish the structure without migrating `apps/docs`.++The API authentication page remains at `api-reference/authentication` but is listed under Developers. A category rename does not require a URL change.diff --git a/apps/website/src/docs/components/DocLinkCard.astro b/apps/website/src/docs/components/DocLinkCard.astronew file mode 100644index 00000000..6f5923b0--- /dev/null+++ b/apps/website/src/docs/components/DocLinkCard.astro@@ -0,0 +1,22 @@+---+import type { Locale } from '../../i18n/i18n.constants';+import { getDocUrl } from '../docs.models';++type Props = {+ title: string;+ docId: string;+ icon?: string;+};++const { title, docId, icon } = Astro.props;+const locale = Astro.params.locale as Locale | undefined;+---++<a+ href={getDocUrl({ docId, locale })}+ class="not-prose group block transition rounded-lg px-6 py-4 border hover:border-primary"+>+ {icon && <div class={`${icon} size-7 text-primary`} aria-hidden="true"></div>}+ <div class="transition group-hover:text-primary text-lg font-semibold mt-3">{title}</div>+ <div class="text-base text-muted-foreground"><slot /></div>+</a>diff --git a/apps/website/src/docs/content/en/concepts/introduction.mdx b/apps/website/src/docs/content/en/concepts/introduction.mdxnew file mode 100644index 00000000..3813de2a--- /dev/null+++ b/apps/website/src/docs/content/en/concepts/introduction.mdx@@ -0,0 +1,10 @@+---+title: How Papra works+description: Understand Papra's behavior and the design choices behind it.+---++This section explains how Papra works and why it behaves the way it does. It is for anyone who wants to understand their archive, not just developers.++Topics include preserving original documents, document deduplication, document processing, and the organization deletion and purge lifecycle.++These explanations will be added as the documentation is migrated. Instructions for using features belong in the user guide; deployment and configuration instructions belong in self-hosting.diff --git a/apps/website/src/docs/content/en/developers/introduction.mdx b/apps/website/src/docs/content/en/developers/introduction.mdxnew file mode 100644index 00000000..1c5324c0--- /dev/null+++ b/apps/website/src/docs/content/en/developers/introduction.mdx@@ -0,0 +1,10 @@+---+title: Build with Papra+description: Automate document workflows and build integrations with Papra.+---++Use Papra's API, SDK, webhooks, and CLI to connect your archive to other tools and automate document workflows.++This section is the home for integration quickstarts, examples, and developer reference material. It will also cover contributing to Papra, including local development and testing.++Start with [API authentication](/docs/api-reference/authentication). More guides and references will be added as the documentation is migrated.diff --git a/apps/website/src/docs/content/en/index.mdx b/apps/website/src/docs/content/en/index.mdxnew file mode 100644index 00000000..70e3d6da--- /dev/null+++ b/apps/website/src/docs/content/en/index.mdx@@ -0,0 +1,31 @@+---+title: Introduction+description: Learn to organize your documents, run your own instance, and build integrations.+---++import DocLinkCard from '../../components/DocLinkCard.astro';++Welcome to the Papra documentation. Learn to organize your documents, run your own instance, and build integrations.++## What is Papra?++Papra is a document archiving platform that allows you to easily store and retrieve your documents. It is designed to be simple and easy to use, while also providing powerful features for managing your documents.++## Get started++To get started with Papra, you can explore the following sections:++<div class="not-prose grid grid-cols-1 lg:grid-cols-2 gap-4 mt-4 mb-12">+ <DocLinkCard title="Use Papra" docId="user-guide/introduction" icon="i-tabler-file-text">+ Archive, organize, and find your documents, on Papra Cloud or your own instance.+ </DocLinkCard>+ <DocLinkCard title="Self-host Papra" docId="self-hosting/getting-started" icon="i-tabler-server">+ Install, configure, and maintain Papra on your own infrastructure.+ </DocLinkCard>+ <DocLinkCard title="Build with Papra" docId="developers/introduction" icon="i-tabler-code">+ Automate workflows and build integrations with the API, SDK, webhooks, and CLI.+ </DocLinkCard>+ <DocLinkCard title="Understand Papra" docId="concepts/introduction" icon="i-tabler-bulb">+ Explore how Papra works and the design choices behind its behavior.+ </DocLinkCard>+</div>diff --git a/apps/website/src/docs/content/en/user-guide/introduction.mdx b/apps/website/src/docs/content/en/user-guide/introduction.mdxnew file mode 100644index 00000000..bab3b3cb--- /dev/null+++ b/apps/website/src/docs/content/en/user-guide/introduction.mdx@@ -0,0 +1,10 @@+---+title: Using Papra+description: Learn to archive, organize, and find your documents with Papra.+---++Papra helps you archive your documents, organize them with tags, and find them again with search.++The user guide is for people using either Papra Cloud or a self-hosted instance. It covers everyday document workflows, search, tagging and automation, importing documents, and working with others in an organization.++Detailed guides will be added as the documentation is migrated.diff --git a/apps/website/src/docs/docs.models.test.ts b/apps/website/src/docs/docs.models.test.tsindex bb2d75b0..ae0f8a26 100644--- a/apps/website/src/docs/docs.models.test.ts+++ b/apps/website/src/docs/docs.models.test.ts@@ -1,5 +1,7 @@import type { CollectionEntry } from 'astro:content';+import { existsSync } from 'node:fs';import { describe, expect, test } from 'vitest';+import { docCategories } from './docs.navigations';import {getDocContext,getDocEditUrl,@@ -30,6 +32,12 @@ describe('getDocUrl', () => {expect(getDocUrl({ locale: 'fr' })).toBe('/fr/docs');});+ test('maps the index document to the landing URL', () => {+ expect(getDocUrl({ docId: 'index' })).toBe('/en/docs');+ expect(getDocUrl({ docId: 'index', locale: 'fr' })).toBe('/fr/docs');+ expect(`${getDocUrl({ docId: 'index' })}.md`).toBe('/en/docs.md');+ });+test('keeps nested logical IDs independent of the locale', () => {expect(getDocUrl({ docId: 'self-hosting/installation/docker' })).toBe('/en/docs/self-hosting/installation/docker',@@ -118,6 +126,35 @@ describe('resolveDoc', () => {});describe('getDocStaticPaths', () => {+ test('serves index at the docs root with normal translation and fallback handling', () => {+ const source = doc('en/index', 'Introduction');+ const paths = getDocStaticPaths([source], ['en', 'fr']);++ expect(paths.map(({ params }) => params)).toEqual([+ { locale: 'en', slug: undefined },+ { locale: 'fr', slug: undefined },+ ]);+ expect(paths[1]?.props).toMatchObject({+ entry: source,+ docId: 'index',+ requestedLocale: 'fr',+ contentLocale: 'en',+ isFallback: true,+ alternateLocales: ['en'],+ });+ expect(getDocEditUrl(paths[1]!.props.entry)).toContain('/content/en/index.mdx');++ const translation = doc('fr/index', 'Présentation');+ const translatedPaths = getDocStaticPaths([source, translation], ['en', 'fr']);+ expect(translatedPaths[1]?.props).toMatchObject({+ entry: translation,+ contentLocale: 'fr',+ isFallback: false,+ alternateLocales: ['en', 'fr'],+ });+ expect(translatedPaths.some(({ params }) => params.slug === 'index')).toBe(false);+ });+test('publishes only enabled docs locales, even when other translations exist', () => {const paths = getDocStaticPaths(docs);expect(paths.map(({ params }) => params)).toEqual([@@ -182,6 +219,47 @@ describe('getDocStaticPaths', () => {});describe('docs navigation', () => {+ test('organizes categories by reader intent', () => {+ expect(docCategories.map((category) => category.titleKey)).toEqual([+ 'docs.categories.overview',+ 'docs.categories.user-guide',+ 'docs.categories.self-hosting',+ 'docs.categories.developers',+ 'docs.categories.concepts',+ ]);+ });++ test('gives every navigation entry one home and an existing English source', () => {+ const docIds = docCategories.flatMap((category) => {+ expect(category.sections.length).toBeGreaterThan(0);+ return category.sections.flatMap((section) => {+ expect(section.items.length).toBeGreaterThan(0);+ return section.items.map((item) => item.docId);+ });+ });++ expect(new Set(docIds).size).toBe(docIds.length);+ for (const docId of docIds) {+ expect(existsSync(new URL(`./content/en/${docId}.mdx`, import.meta.url))).toBe(true);+ }+ });++ test('treats the landing document as a regular Overview entry', () => {+ expect(getDocContext('index')?.category.titleKey).toBe('docs.categories.overview');+ expect(getDocContext('index')?.section.titleKey).toBe('docs.sections.getting-started');+ expect(getDocPagination('index')).toEqual({ previous: undefined, next: undefined });+ });++ test('lists the existing API URL under Developers', () => {+ expect(getDocContext('api-reference/authentication')?.category.titleKey).toBe(+ 'docs.categories.developers',+ );+ expect(getDocPagination('api-reference/authentication')).toEqual({+ previous: { docId: 'developers/introduction' },+ next: undefined,+ });+ });+test('uses locale-independent IDs to find context', () => {expect(getDocContext('self-hosting/installation/docker')?.category.titleKey).toBe('docs.categories.self-hosting',diff --git a/apps/website/src/docs/docs.models.ts b/apps/website/src/docs/docs.models.tsindex 3f1a9ea1..6d5ad3fb 100644--- a/apps/website/src/docs/docs.models.ts+++ b/apps/website/src/docs/docs.models.ts@@ -8,7 +8,7 @@ import { DOCS_LOCALES } from './docs.constants';import { docCategories } from './docs.navigations';// Navigation membership determines context, not the document's path hierarchy.-// The docs landing page and unlisted documents have no active context.+// The landing document uses the logical ID "index", just like other entries.export function getDocContext(docId?: string) {if (!docId) {return undefined;@@ -50,7 +50,10 @@ export function getDocUrl({docId,locale = DEFAULT_LOCALE,}: { docId?: string; locale?: Locale } = {}): string {- return buildLocalizedPath({ locale, path: docId ? `/docs/${docId}` : '/docs' });+ return buildLocalizedPath({+ locale,+ path: docId && docId !== 'index' ? `/docs/${docId}` : '/docs',+ });}export function getDocEditUrl(entry: CollectionEntry<'docs'>): string | undefined {@@ -98,7 +101,8 @@ export function getDocStaticPaths(return locales.flatMap((locale) =>docIds.map((docId) => ({- params: { locale, slug: docId },+ // The index document is served at /docs, never /docs/index.+ params: { locale, slug: docId === 'index' ? undefined : docId },props: {...resolveDoc({ docs, docId, locale }),alternateLocales: locales.filter((candidate) =>diff --git a/apps/website/src/docs/docs.navigations.ts b/apps/website/src/docs/docs.navigations.tsindex bf587c64..0d328309 100644--- a/apps/website/src/docs/docs.navigations.ts+++ b/apps/website/src/docs/docs.navigations.ts@@ -1,6 +1,25 @@import type { DocsCategory } from './docs.types';+// Organize by reader intent; see README.md for category boundaries.export const docCategories: DocsCategory[] = [+ {+ titleKey: 'docs.categories.overview',+ sections: [+ {+ titleKey: 'docs.sections.getting-started',+ items: [{ docId: 'index' }],+ },+ ],+ },+ {+ titleKey: 'docs.categories.user-guide',+ sections: [+ {+ titleKey: 'docs.sections.getting-started',+ items: [{ docId: 'user-guide/introduction' }],+ },+ ],+ },{titleKey: 'docs.categories.self-hosting',sections: [@@ -34,10 +53,14 @@ export const docCategories: DocsCategory[] = [],},{- titleKey: 'docs.categories.api-reference',+ titleKey: 'docs.categories.developers',sections: [{- titleKey: 'docs.sections.authentication',+ titleKey: 'docs.sections.getting-started',+ items: [{ docId: 'developers/introduction' }],+ },+ {+ titleKey: 'docs.sections.api-reference',items: [{docId: 'api-reference/authentication',@@ -46,4 +69,13 @@ export const docCategories: DocsCategory[] = [},],},+ {+ titleKey: 'docs.categories.concepts',+ sections: [+ {+ titleKey: 'docs.sections.overview',+ items: [{ docId: 'concepts/introduction' }],+ },+ ],+ },];diff --git a/apps/website/src/locales/en.ts b/apps/website/src/locales/en.tsindex e13e446a..10994b4f 100644--- a/apps/website/src/locales/en.ts+++ b/apps/website/src/locales/en.ts@@ -355,12 +355,16 @@ export const translations = {'Last Chance: {{percentage}}% off for life - Offer expires December 31st, 2025!',// Documentation (other locales use these English labels until translated)+ 'docs.categories.overview': 'Overview',+ 'docs.categories.user-guide': 'User guide','docs.categories.self-hosting': 'Self-hosting',- 'docs.categories.api-reference': 'API Reference',+ 'docs.categories.developers': 'Developers',+ 'docs.categories.concepts': 'Concepts','docs.sections.getting-started': 'Getting Started','docs.sections.installation': 'Installation','docs.sections.platforms': 'Platforms',- 'docs.sections.authentication': 'Authentication',+ 'docs.sections.api-reference': 'API reference',+ 'docs.sections.overview': 'Overview','docs.skip-to-content': 'Skip to content','docs.categories-label': 'Documentation categories','docs.sidebar-label': 'Documentation sidebar',diff --git a/apps/website/src/pages/[locale]/docs.md.ts b/apps/website/src/pages/[locale]/docs.md.tsnew file mode 100644index 00000000..a055a274--- /dev/null+++ b/apps/website/src/pages/[locale]/docs.md.ts@@ -0,0 +1,17 @@+import type { APIRoute, InferGetStaticPropsType } from 'astro';+import { getCollection } from 'astro:content';+import { formatDocMarkdown } from '../../docs/docs.markdown';+import { getDocStaticPaths } from '../../docs/docs.models';++export async function getStaticPaths() {+ return getDocStaticPaths(await getCollection('docs'))+ .filter(({ props }) => props.docId === 'index')+ .map(({ params: { locale }, props }) => ({ params: { locale }, props }));+}++type Props = InferGetStaticPropsType<typeof getStaticPaths>;++export const GET: APIRoute<Props> = ({ props: { entry } }) =>+ new Response(formatDocMarkdown(entry), {+ headers: { 'Content-Type': 'text/markdown; charset=utf-8' },+ });diff --git a/apps/website/src/pages/[locale]/docs/[...slug].md.ts b/apps/website/src/pages/[locale]/docs/[...slug].md.tsindex 7571fa67..6b49cdfa 100644--- a/apps/website/src/pages/[locale]/docs/[...slug].md.ts+++ b/apps/website/src/pages/[locale]/docs/[...slug].md.ts@@ -4,7 +4,10 @@ import { getDocStaticPaths } from '../../../docs/docs.models';import { formatDocMarkdown } from '../../../docs/docs.markdown';export async function getStaticPaths() {- return getDocStaticPaths(await getCollection('docs'));+ // The landing document's export lives at /<locale>/docs.md.+ return getDocStaticPaths(await getCollection('docs')).filter(+ ({ params }) => params.slug !== undefined,+ );}type Props = InferGetStaticPropsType<typeof getStaticPaths>;diff --git a/apps/website/src/pages/[locale]/docs/index.astro b/apps/website/src/pages/[locale]/docs/index.astrodeleted file mode 100644index 4f8bc537..00000000--- a/apps/website/src/pages/[locale]/docs/index.astro+++ /dev/null@@ -1,89 +0,0 @@-----import type { Locale } from '../../../i18n/i18n.constants';-import { DEFAULT_LOCALE } from '../../../i18n/i18n.constants';-import { DOCS_LOCALES } from '../../../docs/docs.constants';-import { getDocUrl } from '../../../docs/docs.models';-import DocsLayout from '../../../layouts/DocsLayout.astro';--export function getStaticPaths() {- return DOCS_LOCALES.map(locale => ({ params: { locale }, props: { locale } }));-}--type Props = { locale: Locale };-const { locale } = Astro.props;--const getStartedSections = [- {- title: "Features",- icon: "i-tabler-rocket",- description: "Discover the features of Papra and how they can help you manage your projects.",- link: getDocUrl({ locale, docId: 'features' }),- },- {- title: "Selfhosting",- icon: "i-tabler-server",- description: "Get started with selfhosting Papra and learn how to set it up on your own server.",- link: getDocUrl({ locale, docId: 'self-hosting/getting-started' }),- },- {- title: "API Reference",- icon: "i-tabler-cloud-network",- description: "Explore the Papra API and learn how to integrate it into your applications.",- link: getDocUrl({ locale, docId: 'api-reference/authentication' }),- },- {- title: "Contributing",- icon: "i-tabler-users",- description: "Learn how to contribute to the Papra project and become a part of the community.",- link: getDocUrl({ locale, docId: 'contributing' }),- },-];-------<DocsLayout- locale={locale}- contentLocale={DEFAULT_LOCALE}- alternateLocales={[DEFAULT_LOCALE]}- rawTitle="Papra documentation"- description="Learn how to use Papra, host it on your own server, and integrate with its API."->- <div class="doc prose dark:prose-invert max-w-none" lang={DEFAULT_LOCALE} data-pagefind-body>- <h1 data-pagefind-meta="title">Papra documentation</h1>- <p>- Welcome to the Papra documentation! Here you will find all the information you need to get started with Papra, including features details, and selfhosting instructions.- </p>-- <h2>- What is Papra?- </h2>-- <p>- Papra is a document archiving plateform that allows you to easily store and retrieve your documents. It is designed to be simple and easy to use, while also providing powerful features for managing your documents.- </p>-- <h2>- Get started- </h2>-- <p>- To get started with Papra, you can explore the following sections:- </p>-</div>--- <div class="grid grid-cols-1 lg:grid-cols-2 gap-4 mt-4 mb-48">- {getStartedSections.map(section => (- <a href={section.link} class="group transition rounded-lg px-6 py-4 border hover:border-primary ">- <div class={section.icon + " size-7 text-primary"}></div>- <div class="transition group-hover:text-primary text-lg font-semibold mt-3">- {section.title}- </div>- <p class="text-base text-muted-foreground">{section.description}</p>- </a>- ))}- </div>----</DocsLayout>