3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 07:37:19 +02:00
Code Issues Projects Releases Packages Wiki Activity

Add comments

Browse source
This commit is contained in:
Frank Li 2017-08-15 16:55:38 -07:00
parent df0f95e36f
commit 43ef3c8142
22 changed files with 114 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

1
lib/build-files.js
View file

@ -28,5 +28,6 @@ if (!fs.existsSync(CWD + "/siteConfig.js")) {
process.exit(1);
}
// generate all static html files
const generate = require("./server/generate.js");
generate();

4
lib/copy-examples.js
View file

@ -26,7 +26,10 @@ program
.parse(process.argv);
const outerFolder = path.basename(path.dirname(CWD));
// handles cases where feature is "translations", "versions" or neither/not present
if (feature === "translations") {
// copy files for translations
const folder = path.join(__dirname, "..", "examples", "translations");
if (fs.existsSync(CWD + "/../crowdin.yaml")) {
console.log(
@ -74,6 +77,7 @@ if (feature === "translations") {
}
});
} else if (feature === "versions") {
// copy files for versions
const folder = path.join(__dirname, "..", "examples", "versions");
let files = glob.sync(folder + "/**/*");
files.forEach(file => {

1
lib/core/BlogPageLayout.js
View file

@ -14,6 +14,7 @@ const MetadataBlog = require("./MetadataBlog.js");
const React = require("react");
const Site = require("./Site.js");
// used to generate entire blog pages, i.e. collection of truncated blog posts
const BlogPageLayout = React.createClass({
getPageURL(page) {
let url = this.props.config.baseUrl + "blog/";

1
lib/core/BlogPost.js
View file

@ -10,6 +10,7 @@
const Marked = require("./Marked.js");
const React = require("react");
// inner blog component for the article itself, without sidebar/header/footer
class BlogPost extends React.Component {
renderContent() {
let content = this.props.content;

1
lib/core/BlogPostLayout.js
View file

@ -13,6 +13,7 @@ const BlogSidebar = require("./BlogSidebar.js");
const Container = require("./Container.js");
const Site = require("./Site.js");
// used for entire blog posts, i.e., each written blog article with sidebar with site header/footer
class BlogPostLayout extends React.Component {
render() {
return (

1
lib/core/CompLibrary.js
View file

@ -11,6 +11,7 @@ const Marked = require("./Marked.js");
const Container = require("./Container.js");
const GridBlock = require("./GridBlock.js");
// collection of other components to provide to users
module.exports = {
Marked: Marked,
Container: Container,

1
lib/core/Doc.js
View file

@ -10,6 +10,7 @@
const React = require("react");
const Marked = require("./Marked.js");
// inner doc component for article itself
class Doc extends React.Component {
render() {
let editLink =

1
lib/core/DocsLayout.js
View file

@ -14,6 +14,7 @@ const DocsSidebar = require("./DocsSidebar.js");
const Site = require("./Site.js");
const translation = require("../server/translation.js");
// component used to generate whole webpage for docs, including sidebar/header/footer
class DocsLayout extends React.Component {
render() {
const metadata = this.props.metadata;

1
lib/core/Head.js
View file

@ -9,6 +9,7 @@
const React = require("react");
// html head for each page
class Head extends React.Component {
render() {
return (

2
lib/core/Marked.js
View file

@ -7,6 +7,8 @@
* of patent rights can be found in the PATENTS file in the same directory.
*/
/* Marked component is used to parse markdown to html */
const React = require("react");
const Prism = require("./Prism.js");
const Header = require("./Header.js");

2
lib/core/Prism.js
View file

@ -7,6 +7,8 @@
* of patent rights can be found in the PATENTS file in the same directory.
*/
/* Prism is used by Marked to do code syntas highlighting */
const React = require("react");
/**

17
lib/core/Site.js
View file

@ -16,23 +16,8 @@ const translation = require("../server/translation.js");
const CWD = process.cwd();
// Component used to provide same head, header, footer, other scripts to all pages
class Site extends React.Component {
/*
goes in body after navPusher
<script
dangerouslySetInnerHTML={{
__html: `
!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)
){js=d.createElement(s);js.id=id;js.src="https://platform.twitter.com/widgets.js";
fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
`,
}}
/>
*/
render() {
const tagline = translation[this.props.language]
? translation[this.props.language]["localized-strings"].tagline

16
lib/core/nav/HeaderNav.js
View file

@ -23,11 +23,12 @@ if (ENABLE_VERSIONING) {
require("../../server/readMetadata.js").generateDocsMetadata();
const Metadata = require("../metadata.js");
// language dropdown nav item for when translations are enabled
class LanguageDropDown extends React.Component {
render() {
const enabledLanguages = [];
let currentLanguage = "English";
// add all enabled languages to dropdown
translation["languages"].map(lang => {
if (lang.tag == this.props.language) {
currentLanguage = lang.name;
@ -43,11 +44,11 @@ class LanguageDropDown extends React.Component {
</li>
);
});
// if no languages are enabled besides English, return null
if (enabledLanguages.length < 1) {
return null;
}
// add Crowdin project recruiting link
if (siteConfig.recruitingLink) {
enabledLanguages.push(
<li key="recruiting">
@ -94,6 +95,7 @@ class LanguageDropDown extends React.Component {
}
}
// header navbar used by all pages generated with docusaurus
class HeaderNav extends React.Component {
constructor() {
super();
@ -101,10 +103,11 @@ class HeaderNav extends React.Component {
slideoutActive: false
};
}
// function to generate each header link, used with each object in siteConfig.headerLinks
makeLinks(link) {
let href;
if (link.search && this.props.config.algolia) {
// return algolia search bar
return (
<li className="navSearchWrapper reactNavSearchWrapper">
<input id="search_input_react" type="text" placeholder="Search" />
@ -112,12 +115,14 @@ class HeaderNav extends React.Component {
);
} else if (link.languages) {
return (
// return language dropdown
<LanguageDropDown
baseUrl={this.props.baseUrl}
language={this.props.language}
/>
);
} else if (link.doc) {
// set link to document with current page's language/version
let id;
if (!ENABLE_VERSIONING || this.props.version === "next") {
id = this.props.language + "-" + link.doc;
@ -137,6 +142,7 @@ class HeaderNav extends React.Component {
}
href = this.props.config.baseUrl + Metadata[id].permalink;
} else if (link.page) {
// set link to page with current page's language if appropriate
if (fs.existsSync(CWD + "/pages/en/" + link.page + ".js")) {
href =
siteConfig.baseUrl + this.props.language + "/" + link.page + ".html";
@ -144,8 +150,10 @@ class HeaderNav extends React.Component {
href = siteConfig.baseUrl + link.page + ".html";
}
} else if (link.href) {
// set link to specified href
href = link.href;
} else if (link.blog) {
// set link to blog url
href = this.props.baseUrl + "blog";
}
return (

3
lib/core/nav/SideNav.js
View file

@ -61,6 +61,7 @@ class SideNav extends React.Component {
</div>
);
}
// return appropriately translated category string
getLocalizedCategoryString(category) {
let categoryString = translation[this.props.language]
? translation[this.props.language]["localized-strings"][category] ||
@ -68,6 +69,7 @@ class SideNav extends React.Component {
: category;
return categoryString;
}
// return appropriately translated label to use for doc/blog in sidebar
getLocalizedString(metadata) {
let localizedString;
const i18n = translation[this.props.language];
@ -85,6 +87,7 @@ class SideNav extends React.Component {
}
return localizedString;
}
// return link to doc in sidebar
getLink(metadata) {
if (metadata.permalink) {
if (metadata.permalink.match(/^https?:/)) {

2
lib/publish-gh-pages.js
View file

@ -18,6 +18,8 @@ const CIRCLE_PROJECT_REPONAME = process.env.CIRCLE_PROJECT_REPONAME;
const CI_PULL_REQUEST = process.env.CI_PULL_REQUEST;
const remoteBranch = `https://${GIT_USER}@github.com/${CIRCLE_PROJECT_USERNAME}/${CIRCLE_PROJECT_REPONAME}.git`;
// build static html files, then push to gh-pages branch of specified repo
if (!shell.which("git")) {
shell.echo("Sorry, this script requires git");
shell.exit(1);

50
lib/server/generate.js
View file

@ -38,7 +38,7 @@ function execute() {
}
];
}
// create the folder path for a file if it does not exist, then write the file
function writeFileAndCreateFolder(file, content) {
mkdirp.sync(file.replace(new RegExp("/[^/]*$"), ""));
@ -47,6 +47,8 @@ function execute() {
const TABLE_OF_CONTENTS_TOKEN = "<AUTOGENERATED_TABLE_OF_CONTENTS>";
// takes the content of a doc article and returns the content with a table of
// contents inserted
const insertTableOfContents = rawContent => {
const regexp = /\n###\s+(`.*`.*)\n/g;
let match;
@ -62,6 +64,8 @@ function execute() {
return rawContent.replace(TABLE_OF_CONTENTS_TOKEN, tableOfContents);
};
// returns true if a file should be excluded from concatentation to
// default Docusaurus styles
function isSeparateCss(file) {
if (!siteConfig.separateCss) {
return false;
@ -76,6 +80,7 @@ function execute() {
console.log("generate.js triggered...");
// array of tags of enabled languages
const enabledLanguages = [];
languages.filter(lang => lang.enabled).map(lang => {
enabledLanguages.push(lang.tag);
@ -84,6 +89,8 @@ function execute() {
readMetadata.generateDocsMetadata();
const Metadata = require("../core/metadata.js");
// mdToHtml is a map from a markdown file name to its html link, used to
// change relative markdown links that work on GitHub into actual site links
const mdToHtml = {};
Object.keys(Metadata).forEach(id => {
const metadata = Metadata[id];
@ -104,10 +111,10 @@ function execute() {
fs.removeSync(CWD + "/build");
// create html files for all docs
// create html files for all docs by going through all doc ids
Object.keys(Metadata).forEach(id => {
const metadata = Metadata[id];
// determine what file to use according to its id
let file;
if (metadata.original_id) {
if (ENABLE_TRANSLATION && metadata.language !== "en") {
@ -134,7 +141,7 @@ function execute() {
const language = metadata.language;
/* generate table of contents if appropriate */
// generate table of contents if appropriate
if (rawContent && rawContent.indexOf(TABLE_OF_CONTENTS_TOKEN) != -1) {
rawContent = insertTableOfContents(rawContent);
}
@ -146,7 +153,7 @@ function execute() {
)[0];
}
/* replace any links to markdown files to their website html links */
// replace any links to markdown files to their website html links
Object.keys(mdToHtml).forEach(function(key, index) {
let link = mdToHtml[key];
link = link.replace("/en/", "/" + language + "/");
@ -159,6 +166,7 @@ function execute() {
rawContent = rawContent.replace(new RegExp(key, "g"), link);
});
// replace any relative links to static assets to absolute links
rawContent = rawContent.replace(
/\]\(assets\//g,
"](" + siteConfig.baseUrl + "docs/assets/"
@ -176,7 +184,7 @@ function execute() {
writeFileAndCreateFolder(targetFile, str);
});
/* copy docs assets if they exist */
// copy docs assets if they exist
if (fs.existsSync(CWD + "/../docs/assets")) {
fs.copySync(
CWD + "/../docs/assets",
@ -184,7 +192,7 @@ function execute() {
);
}
// create html files for all blog posts
// create html files for all blog posts (each article)
if (fs.existsSync(__dirname + "../core/MetadataBlog.js")) {
fs.removeSync(__dirname + "../core/MetadataBlog.js");
}
@ -199,7 +207,7 @@ function execute() {
return;
}
/* convert filename ot use slashes */
// convert filename to use slashes
const filePath = path
.basename(file)
.replace("-", "/")
@ -233,7 +241,7 @@ function execute() {
CWD + "/build/" + siteConfig.projectName + "/blog/" + filePath;
writeFileAndCreateFolder(targetFile, str);
});
// create html files for all blog pages
// create html files for all blog pages (collections of article previews)
const BlogPageLayout = require("../core/BlogPageLayout.js");
const perPage = 10;
for (let page = 0; page < Math.ceil(MetadataBlog.length / perPage); page++) {
@ -258,7 +266,7 @@ function execute() {
writeFileAndCreateFolder(targetFile, str);
}
/* copy blog assets if they exist */
// copy blog assets if they exist
if (fs.existsSync(CWD + "/blog/assets")) {
fs.copySync(
CWD + "/blog/assets",
@ -266,7 +274,7 @@ function execute() {
);
}
/* copy all static files from docusaurus */
// copy all static files from docusaurus
files = glob.sync(__dirname + "/../static/**");
files.forEach(file => {
let targetFile =
@ -275,6 +283,7 @@ function execute() {
siteConfig.projectName +
"/" +
file.split("/static/")[1];
// parse css files to replace colors according to siteConfig
if (file.match(/\.css$/)) {
let cssContent = fs.readFileSync(file, "utf8");
@ -304,9 +313,10 @@ function execute() {
}
});
/* copy all static files from user */
// copy all static files from user
files = glob.sync(CWD + "/static/**");
files.forEach(file => {
// parse css files to replace colors according to siteConfig
if (file.match(/\.css$/) && !isSeparateCss(file)) {
const mainCss =
CWD + "/build/" + siteConfig.projectName + "/css/main.css";
@ -328,11 +338,12 @@ function execute() {
}
});
/* compile/copy pages from user */
// compile/copy pages from user
files = glob.sync(CWD + "/pages/**");
files.forEach(file => {
// render .js files to strings
if (file.match(/\.js$/)) {
/* make temp file for sake of require paths */
// make temp file for sake of require paths
const parts = file.split("pages");
let tempFile = __dirname + "/../pages" + parts[1];
tempFile = tempFile.replace(
@ -352,10 +363,10 @@ function execute() {
const match = regexLang.exec(file);
const langParts = match[1].split("/");
if (langParts.indexOf("en") !== -1) {
/* copy and compile a page for each enabled language from the English file */
// copy and compile a page for each enabled language from the English file
for (let i = 0; i < enabledLanguages.length; i++) {
let language = enabledLanguages[i];
/* skip conversion from english file if a file exists for this language */
// skip conversion from english file if a file exists for this language
if (
language !== "en" &&
fs.existsSync(file.replace("/en/", "/" + language + "/"))
@ -374,7 +385,7 @@ function execute() {
);
}
} else {
/* allow for rendering of other files not in pages/en folder */
// allow for rendering of other files not in pages/en folder
let language = "en";
for (let i = 0; i < langParts.length; i++) {
if (enabledLanguages.indexOf(langParts[i]) !== -1) {
@ -392,6 +403,7 @@ function execute() {
fs.removeSync(tempFile);
} else if (!fs.lstatSync(file).isDirectory()) {
// copy other non .js files
let parts = file.split("pages");
let targetFile =
CWD + "/build/" + siteConfig.projectName + "/" + parts[1];
@ -400,7 +412,7 @@ function execute() {
}
});
/* copy html files in 'en' to base level as well */
// copy html files in 'en' to base level as well
files = glob.sync(CWD + "/build/" + siteConfig.projectName + "/en/**");
files.forEach(file => {
let targetFile = file.replace("en/", "");
@ -409,7 +421,7 @@ function execute() {
}
});
/* Generate CNAME file if a custom domain is specified in siteConfig */
// Generate CNAME file if a custom domain is specified in siteConfig
if (siteConfig.cname) {
let targetFile = CWD + "/build/" + siteConfig.projectName + "/CNAME";
fs.writeFileSync(targetFile, siteConfig.cname);

2
lib/server/readCategories.js
View file

@ -23,6 +23,8 @@ if (fs.existsSync(CWD + "/languages.js")) {
}
];
}
// returns data broken up into categories for a sidebar
function readCategories(sidebar) {
const enabledLanguages = [];
languages.filter(lang => lang.enabled).map(lang => {

9
lib/server/readMetadata.js
View file

@ -30,6 +30,7 @@ if (fs.existsSync(CWD + "/languages.js")) {
];
}
// returns map from id to object containing sidebar ordering info
function readSidebar() {
let allSidebars;
if (fs.existsSync(CWD + "/sidebars.json")) {
@ -69,6 +70,7 @@ function readSidebar() {
return order;
}
// split markdown header
function splitHeader(content) {
const lines = content.split("\n");
let i = 1;
@ -173,6 +175,7 @@ function processMetadata(file) {
return { metadata, rawContent: rawContent };
}
// process metadata for all docs and save into core/metadata.js
function generateDocsMetadata() {
const order = readSidebar();
@ -185,7 +188,7 @@ function generateDocsMetadata() {
const metadatas = {};
/* metadata for english files */
// metadata for english files
let files = glob.sync(CWD + "/../docs/**");
files.forEach(file => {
let language = "en";
@ -202,7 +205,7 @@ function generateDocsMetadata() {
}
});
/* metadata for non-english docs */
// metadata for non-english docs
files = glob.sync(CWD + "/translated_docs/**");
files.forEach(file => {
let language = "en";
@ -227,6 +230,7 @@ function generateDocsMetadata() {
}
});
// metadata for versioned docs
const versionData = versionFallback.docData();
versionData.forEach(metadata => {
const id = metadata.localized_id;
@ -262,6 +266,7 @@ function generateDocsMetadata() {
);
}
// process metadata for blog posts and save into core/MetadataBlog.js
function generateBlogMetadata() {
const metadatas = [];

37
lib/server/server.js
View file

@ -101,7 +101,7 @@ function execute(port) {
reloadMetadata();
/* handle all requests for document pages */
// handle all requests for document pages
const app = express().get(/docs\/.*html$/, (req, res, next) => {
removeFromCache(CWD + "/siteConfig.js");
siteConfig = require(CWD + "/siteConfig.js");
@ -110,13 +110,15 @@ function execute(port) {
reloadMetadata();
// links is a map from a permalink to an id
// links is a map from a permalink to an id for each document
let links = {};
Object.keys(Metadata).forEach(id => {
const metadata = Metadata[id];
links[metadata.permalink] = id;
});
// mdToHtml is a map from a markdown file name to its html link, used to
// change relative markdown links that work on GitHub into actual site links
const mdToHtml = {};
Object.keys(Metadata).forEach(id => {
const metadata = Metadata[id];
@ -140,6 +142,7 @@ function execute(port) {
}
const language = metadata.language;
// determine what file to use according to its id
let file;
if (metadata.original_id) {
if (ENABLE_TRANSLATION && metadata.language !== "en") {
@ -165,7 +168,7 @@ function execute(port) {
let rawContent = readMetadata.extractMetadata(fs.readFileSync(file, "utf8"))
.rawContent;
/* generate table of contents if appropriate */
// generate table of contents if appropriate
if (rawContent && rawContent.indexOf(TABLE_OF_CONTENTS_TOKEN) !== -1) {
rawContent = insertTableOfContents(rawContent);
}
@ -177,7 +180,7 @@ function execute(port) {
)[0];
}
/* replace any links to markdown files to their website html links */
// replace any links to markdown files to their website html links
Object.keys(mdToHtml).forEach(function(key, index) {
let link = mdToHtml[key];
link = link.replace("/en/", "/" + language + "/");
@ -193,6 +196,7 @@ function execute(port) {
);
});
// replace any relative links to static assets to absolute links
rawContent = rawContent.replace(
/\]\(assets\//g,
"](" + siteConfig.baseUrl + "docs/assets/"
@ -209,7 +213,7 @@ function execute(port) {
res.send(renderToStaticMarkup(docComp));
});
/* handle all requests for blog pages and posts */
// handle all requests for blog pages and posts
app.get(/blog\/.*html$/, (req, res) => {
removeFromCache(CWD + "/siteConfig.js");
siteConfig = require(CWD + "/siteConfig.js");
@ -220,11 +224,11 @@ function execute(port) {
readMetadata.generateBlogMetadata();
const MetadataBlog = require("../core/MetadataBlog.js");
/* generate all of the blog pages */
// generate all of the blog pages
removeFromCache("../core/BlogPageLayout.js");
const BlogPageLayout = require("../core/BlogPageLayout.js");
const blogPages = {};
/* make blog pages with 10 posts per page */
// make blog pages with 10 posts per page
const perPage = 10;
for (
let page = 0;
@ -296,12 +300,12 @@ function execute(port) {
}
});
/* handle all other main pages */
// handle all other main pages
app.get("*.html", (req, res, next) => {
removeFromCache(CWD + "/siteConfig.js");
siteConfig = require(CWD + "/siteConfig.js");
/* look for user provided html file first */
// look for user provided html file first
let htmlFile = req.path.toString().replace(siteConfig.baseUrl, "");
htmlFile = CWD + "/pages/" + htmlFile;
if (
@ -317,7 +321,7 @@ function execute(port) {
return;
}
/* look for user provided react file either in specified path or in path for english files */
// look for user provided react file either in specified path or in path for english files
let file = req.path.toString().replace(/\.html$/, ".js");
file = file.replace(siteConfig.baseUrl, "");
let userFile = CWD + "/pages/" + file;
@ -340,8 +344,8 @@ function execute(port) {
englishFile = englishFile.replace("/" + language + "/", "/en/");
}
/* check for: a file for the page, an english file for page with unspecified language,
english file for the page */
// check for: a file for the page, an english file for page with unspecified language,
// english file for the page
if (
fs.existsSync(userFile) ||
fs.existsSync(
@ -352,7 +356,7 @@ function execute(port) {
) ||
fs.existsSync((userFile = englishFile))
) {
/* copy into docusaurus so require paths work */
// copy into docusaurus so require paths work
let parts = userFile.split("pages/");
let tempFile = __dirname + "/../pages/" + parts[1];
tempFile = tempFile.replace(
@ -362,7 +366,7 @@ function execute(port) {
mkdirp.sync(tempFile.replace(new RegExp("/[^/]*$"), ""));
fs.copySync(userFile, tempFile);
/* render into a string */
// render into a string
removeFromCache(tempFile);
const ReactComp = require(tempFile);
removeFromCache("../core/Site.js");
@ -383,7 +387,7 @@ function execute(port) {
}
});
/* generate the main.css file by concatenating user provided css to the end */
// generate the main.css file by concatenating user provided css to the end
app.get(/main\.css$/, (req, res) => {
const mainCssPath =
__dirname +
@ -422,6 +426,7 @@ function execute(port) {
res.send(cssContent);
});
// serve static assets from these locations
app.use(
siteConfig.baseUrl + "docs/assets/",
express.static(CWD + "/../docs/assets")
@ -433,6 +438,8 @@ function execute(port) {
app.use(siteConfig.baseUrl, express.static(CWD + "/static"));
app.use(siteConfig.baseUrl, express.static(__dirname + "/../static"));
// "redirect" requests to pages ending with "/" or no extension so that
// request to "...blog" returns same result as "...blog/index.html"
app.get(/\/[^\.]*\/?$/, (req, res) => {
if (req.path.toString().endsWith("/")) {
request.get(

11
lib/server/translation.js
View file

@ -1,3 +1,14 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
* All rights reserved.
*
* This source code is licensed under the BSD-style license found in the
* LICENSE file in the root directory of this source tree. An additional grant
* of patent rights can be found in the PATENTS file in the same directory.
*/
// translation object contains all translations for each string in 18n/en.json
const CWD = process.cwd();
const fs = require("fs");
const glob = require("glob");

1
lib/start-server.js
View file

@ -34,5 +34,6 @@ program.option("--port <number>", "Specify port number").parse(process.argv);
const port = program.port || 3000;
// start local server on specified port
const server = require("./server/server.js");
server(port);

8
lib/write-translations.js
View file

@ -37,7 +37,7 @@ function execute() {
"pages-strings": {}
};
/* look through front matter of docs for titles and categories to translate */
// look through markdown headers of docs for titles and categories to translate
let files = glob.sync(CWD + "/../docs/**");
files.forEach(file => {
const extension = path.extname(file);
@ -56,14 +56,14 @@ function execute() {
}
}
});
/* look through header links for text to translate */
// look through header links for text to translate
siteConfig.headerLinks.forEach(link => {
if (link.label) {
translations["localized-strings"][link.label] = link.label;
}
});
/* find sidebar category titles to translate */
// find sidebar category titles to translate
Object.keys(sidebars).forEach(sb => {
const categories = sidebars[sb];
Object.keys(categories).forEach(category => {
@ -85,7 +85,7 @@ function execute() {
});
});
/* go through pages to look for text inside translate tags */
// go through pages to look for text inside translate tags
files = glob.sync(CWD + "/pages/en/**");
files.forEach(file => {
const extension = path.extname(file);