mirror of
https://github.com/outline/outline.git
synced 2026-11-22 14:01:41 +03:00
115 lines
3.6 KiB
TypeScript
115 lines
3.6 KiB
TypeScript
import yaml from "js-yaml";
|
|
import type Document from "@server/models/Document";
|
|
|
|
interface Frontmatter {
|
|
type: string;
|
|
title: string;
|
|
description?: string;
|
|
resource: string;
|
|
status: "draft" | "stable" | "deprecated";
|
|
generated: { by: string; at: string };
|
|
}
|
|
|
|
interface IndexEntry {
|
|
/** The display name of the entry. */
|
|
title: string;
|
|
/** The path of the entry relative to the index file. */
|
|
path: string;
|
|
/** A short description of the entry, if any. */
|
|
description?: string | null;
|
|
}
|
|
|
|
/**
|
|
* Helpers for writing documents in the Open Knowledge Format (OKF), a bundle
|
|
* of markdown files with YAML frontmatter.
|
|
*
|
|
* @see https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
|
|
*/
|
|
export default class OKFHelper {
|
|
/** The version of the specification the exported bundle targets. */
|
|
public static readonly version = "0.2";
|
|
|
|
/** Name of the directory listing entry. */
|
|
public static readonly indexFileName = "index.md";
|
|
|
|
/** File names that may not be used for a concept document. */
|
|
public static readonly reservedFileNames = ["index.md", "log.md"];
|
|
|
|
/** The concept type written to every exported document. */
|
|
public static readonly conceptType = "Document";
|
|
|
|
/**
|
|
* Whether a file name is reserved by the format and cannot hold a document.
|
|
*
|
|
* @param fileName The file name, without any directory.
|
|
* @returns true if the name is reserved.
|
|
*/
|
|
public static isReservedFileName(fileName: string): boolean {
|
|
return this.reservedFileNames.includes(fileName.toLowerCase());
|
|
}
|
|
|
|
/**
|
|
* Builds the frontmatter block that precedes a document's markdown body.
|
|
*
|
|
* @param document The document being exported.
|
|
* @param origin The origin of the team's URL, used to build the canonical
|
|
* URL of the document.
|
|
* @returns The YAML frontmatter, including delimiters and a trailing blank
|
|
* line that separates it from the body.
|
|
*/
|
|
public static frontmatter(document: Document, origin: string): string {
|
|
const description = this.singleLine(document.getSummary());
|
|
const actor = document.updatedBy ?? document.createdBy;
|
|
|
|
const data: Frontmatter = {
|
|
type: this.conceptType,
|
|
title: document.displayTitle,
|
|
...(description ? { description } : {}),
|
|
resource: `${origin}${document.path}`,
|
|
status: this.status(document),
|
|
generated: {
|
|
by: `human:${actor.email ?? actor.id}`,
|
|
at: document.updatedAt.toISOString(),
|
|
},
|
|
};
|
|
|
|
return this.serialize(data);
|
|
}
|
|
|
|
/**
|
|
* Builds the bundle-root index that declares the format version and lists
|
|
* the top-level entries of the bundle.
|
|
*
|
|
* @param heading The heading the entries are grouped under.
|
|
* @param entries The entries to list.
|
|
* @returns The contents of the root index.md.
|
|
*/
|
|
public static rootIndex(heading: string, entries: IndexEntry[]): string {
|
|
const lines = entries.map((entry) => {
|
|
const description = this.singleLine(entry.description);
|
|
const link = `[${entry.title}](${encodeURI(entry.path)})`;
|
|
return description ? `* ${link} - ${description}` : `* ${link}`;
|
|
});
|
|
|
|
return `${this.serialize({ okf_version: this.version })}# ${heading}\n\n${lines.join("\n")}\n`;
|
|
}
|
|
|
|
private static status(document: Document): "draft" | "stable" | "deprecated" {
|
|
if (document.archivedAt) {
|
|
return "deprecated";
|
|
}
|
|
if (!document.publishedAt) {
|
|
return "draft";
|
|
}
|
|
return "stable";
|
|
}
|
|
|
|
private static singleLine(value?: string | null): string {
|
|
return (value ?? "").replace(/\s+/g, " ").trim();
|
|
}
|
|
|
|
private static serialize(data: object): string {
|
|
return `---\n${yaml.dump(data, { lineWidth: -1, noRefs: true })}---\n\n`;
|
|
}
|
|
}
|