feat:docs translation + versioning 💥

This commit is contained in:
endiliey 2018-09-07 20:41:04 +08:00
parent 31d333b82f
commit 0f38ae3979
20 changed files with 1133 additions and 520 deletions

View file

@ -1,37 +1,113 @@
const fs = require('fs-extra');
const path = require('path');
const fm = require('front-matter');
const globby = require('globby');
const {encodePath, fileToPath} = require('../utils');
const createOrder = require('./order');
const loadSidebars = require('./sidebars');
const processMetadata = require('./metadata');
const {getSubFolder, idx} = require('../utils');
function parse(fileString) {
if (!fm.test(fileString)) {
return {metadata: null, content: fileString};
}
const {attributes: metadata, body: content} = fm(fileString);
async function loadDocs({siteDir, docsDir, env}) {
// @tested - load all sidebars including versioned sidebars
const allSidebars = loadSidebars({siteDir, env});
return {metadata, content};
}
// @tested - build the docs ordering such as next, previous, category and sidebar
const order = createOrder(allSidebars);
async function loadDocs(docsDir) {
/* Settle versions & translations from environment */
const translationEnabled = idx(env, ['translation', 'enabled']);
const enabledLanguages =
translationEnabled && idx(env, ['translation', 'enabledLanguages']);
const enabledLangTags =
(enabledLanguages && enabledLanguages.map(lang => lang.tag)) || [];
const defaultLanguage = idx(env, ['translation', 'defaultLanguage']);
const defaultLangTag = defaultLanguage && defaultLanguage.tag;
const versioningEnabled = idx(env, ['versioning', 'enabled']);
const versions =
(versioningEnabled && idx(env, ['versioning', 'versions'])) || [];
/* Prepare metadata container */
const metadatas = {};
/* metadata for default docs files */
const docsFiles = await globby(['**/*.md'], {
cwd: docsDir
});
const docsData = await Promise.all(
await Promise.all(
docsFiles.map(async source => {
const filepath = path.resolve(docsDir, source);
const fileString = await fs.readFile(filepath, 'utf-8');
const {metadata} = parse(fileString);
/*
Do not allow reserved version/ translated folder name in 'docs'
e.g: 'docs/version-1.0.0/' should not be allowed as it can cause unwanted bug
*/
const subFolder = getSubFolder(path.resolve(docsDir, source), docsDir);
const versionsFolders = versions.map(version => `version-${version}`);
if ([...enabledLangTags, ...versionsFolders].includes(subFolder)) {
throw new Error(`You cannot have a folder named 'docs/${subFolder}/'`);
}
return {
path: encodePath(fileToPath(source)),
source,
...metadata
};
const metadata = await processMetadata(source, docsDir, env, order);
metadatas[metadata.id] = metadata;
})
);
return docsData;
/* metadata for non-default-language docs */
const translatedDir = path.join(siteDir, 'translated_docs');
const translatedFiles = await globby(['**/*.md'], {
cwd: translatedDir
});
await Promise.all(
translatedFiles.map(async source => {
/*
Do not process disabled & default languages folder in `translated_docs`
e.g: 'translated_docs/ja/**' should not be allowed if lang 'ja' is disabled
*/
const translatedFilePath = path.resolve(translatedDir, source);
const detectedLangTag = getSubFolder(translatedFilePath, translatedDir);
if (
detectedLangTag === defaultLangTag ||
!enabledLangTags.includes(detectedLangTag)
) {
return;
}
const metadata = await processMetadata(source, translatedDir, env, order);
metadatas[metadata.id] = metadata;
})
);
/* metadata for versioned docs */
const versionedDir = path.join(siteDir, 'versioned_docs');
const versionedFiles = await globby(['**/*.md'], {
cwd: versionedDir
});
await Promise.all(
versionedFiles.map(async source => {
const metadata = await processMetadata(source, versionedDir, env, order);
metadatas[metadata.id] = metadata;
})
);
/*
Get the titles of the previous and next ids so that we can use them
*/
Object.keys(metadatas).forEach(metadata => {
if (metadatas[metadata].previous) {
if (metadatas[metadatas[metadata].previous]) {
metadatas[metadata].previous_title =
metadatas[metadatas[metadata].previous].title;
} else {
metadatas[metadata].previous_title = 'Previous';
}
}
if (metadatas[metadata].next) {
if (metadatas[metadatas[metadata].next]) {
metadatas[metadata].next_title =
metadatas[metadatas[metadata].next].title;
} else {
metadatas[metadata].next_title = 'Next';
}
}
});
return metadatas;
}
module.exports = loadDocs;

127
lib/load/docs/metadata.js Normal file
View file

@ -0,0 +1,127 @@
const fs = require('fs-extra');
const path = require('path');
const {getSubFolder, idx, parse} = require('../utils');
function getLanguage(filepath, refDir, env) {
const translationEnabled = idx(env, ['translation', 'enabled']);
if (translationEnabled) {
const detectedLangTag = getSubFolder(filepath, refDir);
const defaultLanguage = idx(env, ['translation', 'defaultLanguage']);
if (!detectedLangTag && defaultLanguage && defaultLanguage.tag) {
return defaultLanguage.tag;
}
const enabledLanguages = idx(env, ['translation', 'enabledLanguages']);
const langTags =
(enabledLanguages && enabledLanguages.map(lang => lang.tag)) || [];
return langTags.find(langTag => langTag === detectedLangTag);
}
return undefined;
}
function getVersion(filepath, refDir, env) {
const versioningEnabled = idx(env, ['versioning', 'enabled']);
if (versioningEnabled) {
const subFolder = getSubFolder(filepath, refDir);
if (!subFolder) {
return 'next';
}
const detectedVersion = subFolder.replace(/^version-/, '');
const versions = idx(env, ['versioning', 'versions']) || [];
if (versions.includes(detectedVersion)) {
return detectedVersion;
}
return 'next';
}
return undefined;
}
module.exports = async function processMetadata(source, refDir, env, order) {
const filepath = path.resolve(refDir, source);
const fileString = await fs.readFile(filepath, 'utf-8');
const {metadata} = parse(fileString);
/* source (relative to refDir) */
metadata.source = source;
/* default id is the file name */
if (!metadata.id) {
metadata.id = path.basename(source, path.extname(source));
}
if (metadata.id.includes('/')) {
throw new Error('Document id cannot include "/".');
}
/* default title is the id */
if (!metadata.title) {
metadata.title = metadata.id;
}
/* language */
const language = getLanguage(filepath, refDir, env);
metadata.language = language;
const langPart = (language && `${language}/`) || '';
/* version */
const versionRefDir = language ? path.join(refDir, language) : refDir;
const version = getVersion(filepath, versionRefDir, env);
metadata.version = version;
const latestVersion = idx(env, ['versioning', 'latestVersion']);
const versionPart =
(version && version !== latestVersion && `${version}/`) || '';
/*
Convert temporarily metadata.id to the form of dirname/id without version/lang prefix
ex: file `versioned_docs/version-1.0.0/en/foo/bar.md` with id `version-1.0.0-bar` => `foo/bar`
*/
if (version) {
metadata.id = metadata.id.replace(new RegExp(`^version-${version}-`), '');
}
const dirName = path.dirname(source);
if (dirName !== '.') {
let prefix = dirName;
if (version) {
prefix = prefix.replace(new RegExp(`^version-${version}`), '');
}
if (language) {
prefix = prefix.replace(new RegExp(`^${language}`), '');
}
if (prefix) {
prefix = prefix.replace(/^\//, '');
metadata.id = `${prefix}/${metadata.id}`;
}
}
/* Build the permalink without baseUrl */
metadata.permalink = `docs/${langPart}${versionPart}${metadata.id}`;
/* if version */
if (version && version !== 'next') {
metadata.id = `version-${version}-${metadata.id}`;
}
/* if language */
if (language) {
metadata.id = `${language}-${metadata.id}`;
}
/* localize id */
metadata.localized_id = metadata.id;
/* Determine order */
const id = metadata.localized_id;
if (order[id]) {
metadata.sidebar = order[id].sidebar;
metadata.category = order[id].category;
if (order[id].next) {
metadata.next_id = order[id].next;
metadata.next = (language ? `${language}-` : '') + order[id].next;
}
if (order[id].previous) {
metadata.previous_id = order[id].previous;
metadata.previous = (language ? `${language}-` : '') + order[id].previous;
}
}
return metadata;
};

View file

@ -1,34 +1,36 @@
// build the docs meta such as next, previous, category and sidebar
module.exports = function createOrder(allSidebars = {}) {
const order = {};
if (!allSidebars) {
return order;
}
Object.keys(allSidebars).forEach(sidebar => {
const categories = allSidebars[sidebar];
let ids = [];
const categoryOrder = [];
Object.keys(categories).forEach(category => {
ids = ids.concat(categories[category]);
for (let i = 0; i < categories[category].length; i++) {
categoryOrder.push(category);
}
});
for (let i = 0; i < ids.length; i++) {
const id = ids[i];
let previous;
let next;
if (i > 0) previous = ids[i - 1];
if (i < ids.length - 1) next = ids[i + 1];
order[id] = {
previous,
next,
sidebar,
category: categoryOrder[i]
};
}
});
return order;
};
// build the docs meta such as next, previous, category and sidebar
module.exports = function createOrder(allSidebars = {}) {
const order = {};
if (!allSidebars) {
return order;
}
Object.keys(allSidebars).forEach(sidebar => {
const categories = allSidebars[sidebar];
let ids = [];
const categoryOrder = [];
Object.keys(categories).forEach(category => {
ids = ids.concat(categories[category]);
// eslint-disable-next-line
for (let i = 0; i < categories[category].length; i++) {
categoryOrder.push(category);
}
});
// eslint-disable-next-line
for (let i = 0; i < ids.length; i++) {
const id = ids[i];
let previous;
let next;
if (i > 0) previous = ids[i - 1];
if (i < ids.length - 1) next = ids[i + 1];
order[id] = {
previous,
next,
sidebar,
category: categoryOrder[i]
};
}
});
return order;
};

View file

@ -1,34 +1,35 @@
const fs = require('fs-extra');
const path = require('path');
const {idx} = require('../utils');
module.exports = function loadSidebars({siteDir, env}) {
let allSidebars = {};
// current sidebars
const sidebarsJSONFile = path.join(siteDir, 'sidebars.json');
if (fs.existsSync(sidebarsJSONFile)) {
allSidebars = require(sidebarsJSONFile);
}
// versioned sidebars
if (idx(env, ['versioning', 'enabled'])) {
const versions = idx(env, ['versioning', 'versions']);
versions &&
versions.forEach(version => {
const versionedSidebarsJSONFile = path.join(
siteDir,
'versioned_sidebars',
`version-${version}-sidebars.json`
);
if (fs.existsSync(versionedSidebarsJSONFile)) {
const sidebar = require(versionedSidebarsJSONFile);
Object.assign(allSidebars, sidebar);
} else {
const missingFile = path.relative(siteDir, versionedSidebarsJSONFile);
throw new Error(`Failed to load ${missingFile}. It does not exist.`);
}
});
}
return allSidebars;
};
const fs = require('fs-extra');
const path = require('path');
const {idx} = require('../utils');
module.exports = function loadSidebars({siteDir, env}) {
let allSidebars = {};
// current sidebars
const sidebarsJSONFile = path.join(siteDir, 'sidebars.json');
if (fs.existsSync(sidebarsJSONFile)) {
allSidebars = require(sidebarsJSONFile); // eslint-disable-line
}
// versioned sidebars
if (idx(env, ['versioning', 'enabled'])) {
const versions = idx(env, ['versioning', 'versions']);
if (Array.isArray(versions)) {
versions.forEach(version => {
const versionedSidebarsJSONFile = path.join(
siteDir,
'versioned_sidebars',
`version-${version}-sidebars.json`
);
if (fs.existsSync(versionedSidebarsJSONFile)) {
const sidebar = require(versionedSidebarsJSONFile); // eslint-disable-line
Object.assign(allSidebars, sidebar);
} else {
const missingFile = path.relative(siteDir, versionedSidebarsJSONFile);
throw new Error(`Failed to load ${missingFile}. It does not exist.`);
}
});
}
}
return allSidebars;
};