The minimalistic document archiving platform.
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,
getDocPagination,
getDocStaticPaths,
getDocUrl,
resolveDoc,
} from './docs.models';
function doc(id: string, title = id): CollectionEntry<'docs'> {
return {
id,
collection: 'docs',
filePath: `src/docs/content/${id}.mdx`,
data: { title, description: title },
};
}
const docs = [
doc('en/self-hosting/getting-started', 'Getting started'),
doc('en/self-hosting/installation/docker', 'Docker'),
doc('fr/self-hosting/getting-started', 'Bien démarrer'),
];
describe('getDocUrl', () => {
test('prefixes the docs landing page with the default locale', () => {
expect(getDocUrl()).toBe('/en/docs');
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',
);
expect(getDocUrl({ docId: 'self-hosting/installation/docker', locale: 'fr' })).toBe(
'/fr/docs/self-hosting/installation/docker',
);
});
});
describe('getDocEditUrl', () => {
test.each([
['en', 'self-hosting/installation/docker', 'en/self-hosting/installation/docker'],
['fr', 'self-hosting/getting-started', 'fr/self-hosting/getting-started'],
['fr', 'self-hosting/installation/docker', 'en/self-hosting/installation/docker'],
] as const)('links to the resolved source for %s/%s', (locale, docId, sourceId) => {
const { entry } = resolveDoc({ docs, docId, locale });
expect(getDocEditUrl(entry)).toBe(
`https://github.com/papra-hq/papra/edit/main/apps/website/src/docs/content/${sourceId}.mdx`,
);
});
test('preserves the source filename and extension and encodes URL-sensitive characters', () => {
const entry = {
...doc('en/unlisted'),
filePath: 'src/docs/content/en/Unlisted page #1.md',
};
expect(getDocEditUrl(entry)).toBe(
'https://github.com/papra-hq/papra/edit/main/apps/website/src/docs/content/en/Unlisted%20page%20%231.md',
);
});
test('omits the link for entries without a source file', () => {
expect(getDocEditUrl({ ...doc('en/unlisted'), filePath: undefined })).toBeUndefined();
});
});
describe('resolveDoc', () => {
test('resolves English without marking it as a fallback', () => {
expect(resolveDoc({ docs, docId: 'self-hosting/getting-started' })).toEqual({
entry: docs[0],
docId: 'self-hosting/getting-started',
requestedLocale: 'en',
contentLocale: 'en',
isFallback: false,
});
});
test('prefers the requested translation, including its title', () => {
expect(resolveDoc({ docs, docId: 'self-hosting/getting-started', locale: 'fr' })).toEqual({
entry: docs[2],
docId: 'self-hosting/getting-started',
requestedLocale: 'fr',
contentLocale: 'fr',
isFallback: false,
});
});
test('falls back to English without losing the requested locale', () => {
const resolved = resolveDoc({ docs, docId: 'self-hosting/installation/docker', locale: 'fr' });
expect(resolved).toEqual({
entry: docs[1],
docId: 'self-hosting/installation/docker',
requestedLocale: 'fr',
contentLocale: 'en',
isFallback: true,
});
expect(getDocUrl({ docId: resolved.docId, locale: resolved.requestedLocale })).toBe(
'/fr/docs/self-hosting/installation/docker',
);
});
test('fails explicitly for missing documents', () => {
expect(() => resolveDoc({ docs, docId: 'missing', locale: 'fr' })).toThrow(
'Missing English source document: missing',
);
});
test('requires an English source for translations', () => {
expect(() =>
resolveDoc({ docs: [docs[2]!], docId: 'self-hosting/getting-started', locale: 'fr' }),
).toThrow('Missing English source document');
});
});
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([
{ locale: 'en', slug: 'self-hosting/getting-started' },
{ locale: 'en', slug: 'self-hosting/installation/docker' },
]);
expect(paths.every(({ props }) => props.alternateLocales.join() === 'en')).toBe(true);
});
test('generates translated and fallback pages, advertising only real translations', () => {
const paths = getDocStaticPaths(docs, ['en', 'fr']);
expect(paths).toHaveLength(4);
expect(paths.map(({ params }) => params)).toContainEqual({
locale: 'fr',
slug: 'self-hosting/installation/docker',
});
expect(
paths.map(({ props }) => ({
locale: props.requestedLocale,
docId: props.docId,
isFallback: props.isFallback,
alternateLocales: props.alternateLocales,
})),
).toEqual([
{
locale: 'en',
docId: 'self-hosting/getting-started',
isFallback: false,
alternateLocales: ['en', 'fr'],
},
{
locale: 'en',
docId: 'self-hosting/installation/docker',
isFallback: false,
alternateLocales: ['en'],
},
{
locale: 'fr',
docId: 'self-hosting/getting-started',
isFallback: false,
alternateLocales: ['en', 'fr'],
},
{
locale: 'fr',
docId: 'self-hosting/installation/docker',
isFallback: true,
alternateLocales: ['en'],
},
]);
});
test('does not generate unknown document routes', () => {
expect(getDocStaticPaths([])).toEqual([]);
expect(getDocStaticPaths(docs).some(({ params }) => params.slug === 'missing')).toBe(false);
});
test('fails the build for a translation without an English source', () => {
expect(() => getDocStaticPaths([doc('fr/orphan')])).toThrow(
'Missing English source document: orphan',
);
});
});
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',
);
expect(getDocContext()).toBeUndefined();
expect(getDocContext('unlisted')).toBeUndefined();
});
test('keeps pagination within the current category', () => {
expect(getDocPagination('self-hosting/getting-started')).toEqual({
previous: undefined,
next: { docId: 'self-hosting/chosing-a-method' },
});
expect(getDocPagination('self-hosting/installation/umbrel')).toEqual({
previous: { docId: 'self-hosting/installation/docker' },
next: undefined,
});
expect(getDocPagination('unlisted')).toEqual({ previous: undefined, next: undefined });
});
});