From b150a94bc1c26e1c333ee1e1e4e672aba54ad912 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Wed, 12 Jul 2017 16:30:15 -0700 Subject: [PATCH 01/16] Update README.md --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 1fdb8b79da..7d857522d5 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,17 @@ In your project repo, all of your documentation files should be placed inside a `docs` folder. Any blog posts should be inside a `blog` folder. Create a `website` folder inside which you will install and run docusaurus. +Example project structure: +``` +project-repo/ + blog/ + 2017-05-06-blog-post.md + docs/ + en/ + doc1.md + website/ +``` + ### Installation Inside of your `website` folder, create a `package.json` file with the following scripts for Docusaurus: From 72328ef4a986ff39503ec4feed948c2abacd8ee9 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Thu, 13 Jul 2017 13:40:24 -0700 Subject: [PATCH 02/16] Use flag for server port number --- lib/start-server.js | 9 +++++---- package.json | 1 + 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/lib/start-server.js b/lib/start-server.js index 66a17aa2e6..857de12aa3 100644 --- a/lib/start-server.js +++ b/lib/start-server.js @@ -15,10 +15,11 @@ require("babel-register")({ presets: ["react"] }); -let port = 3000; -if (process.argv.length > 2) { - port = process.argv[2]; -} +const program = require("commander"); + +program.option("--port ", "Specify port number").parse(process.argv); + +const port = program.port || 3000; const server = require("./server/server.js"); server(port); diff --git a/package.json b/package.json index 90f4a8686d..8884377617 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,7 @@ "babel-traverse": "^6.25.0", "babylon": "^6.17.4", "classnames": "^2.2.5", + "commander": "^2.11.0", "express": "^4.15.3", "fs-extra": "^3.0.1", "glob": "^7.1.2", From 70ed75b04629e30a341be6cb951c9a3bf1fd37b5 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Thu, 13 Jul 2017 15:09:52 -0700 Subject: [PATCH 03/16] Publish changes to start args to npm --- README.md | 6 ++++-- docs/en/getting-started.md | 17 +++++++++++++++-- package.json | 2 +- 3 files changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 7d857522d5..28845025e2 100644 --- a/README.md +++ b/README.md @@ -140,8 +140,10 @@ yarn run start ``` -This will start a server hosting your website locally at `localhost:3000`. This server will ignore any occurences `siteConfig.baseUrl` in URLs, e.g. `localhost:3000/your-site/index.html` will be the same as `localhost:3000/index.html`. Any changes to configured files will be reflected by refreshing the page, i.e. the server does not need to be restarted to show changes. You may also specify a different port to start your server on as a command line argument, e.g. `npm run start 9000`. - +This will start a server hosting your website locally at `localhost:3000`. This server will ignore any occurences `siteConfig.baseUrl` in URLs, e.g. `localhost:3000/your-site/index.html` will be the same as `localhost:3000/index.html`. Any changes to configured files will be reflected by refreshing the page, i.e. the server does not need to be restarted to show changes. You may also specify a different port to start your server on by using a `--port` flag: +``` +npm run start -- --port 9000 +``` ### Build Static Pages diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md index 0e0cfae02f..484cf77f91 100644 --- a/docs/en/getting-started.md +++ b/docs/en/getting-started.md @@ -13,6 +13,17 @@ next: translation In your project repo, all of your documentation files should be placed inside a `docs` folder. Any blog posts should be inside a `blog` folder. Create a `website` folder inside which you will install and run docusaurus. +Example project structure: +``` +project-repo/ + blog/ + 2017-05-06-blog-post.md + docs/ + en/ + doc1.md + website/ +``` + ### Installation Inside of your `website` folder, create a `package.json` file with the following scripts for Docusaurus: @@ -136,8 +147,10 @@ yarn run start ``` -This will start a server hosting your website locally at `localhost:3000`. This server will ignore any occurences `siteConfig.baseUrl` in URLs, e.g. `localhost:3000/your-site/index.html` will be the same as `localhost:3000/index.html`. Any changes to configured files will be reflected by refreshing the page, i.e. the server does not need to be restarted to show changes. You may also specify a different port to start your server on as a command line argument, e.g. `npm run start 9000`. - +This will start a server hosting your website locally at `localhost:3000`. This server will ignore any occurences `siteConfig.baseUrl` in URLs, e.g. `localhost:3000/your-site/index.html` will be the same as `localhost:3000/index.html`. Any changes to configured files will be reflected by refreshing the page, i.e. the server does not need to be restarted to show changes. You may also specify a different port to start your server on by using a `--port` flag: +``` +npm run start -- --port 9000 +``` ### Build Static Pages diff --git a/package.json b/package.json index 8884377617..fadf9b714b 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,7 @@ "shelljs": "^0.7.8" }, "name": "docusaurus", - "version": "1.0.0-alpha.14", + "version": "1.0.0-alpha.15", "bin": { "docusaurus-start": "./lib/start-server.js", "docusaurus-build": "./lib/build-files.js", From 833d9d30a102121021e494a77744950c5ed264cc Mon Sep 17 00:00:00 2001 From: Frank Li Date: Thu, 13 Jul 2017 15:27:24 -0700 Subject: [PATCH 04/16] Fix search bar positioning in header Adding this style change should fix the search bar. Could someone advise on where the best place to put it in the file would actually be, and if this is the right way to approach a fix? Thanks. --- lib/static/css/main.css | 3 +++ 1 file changed, 3 insertions(+) diff --git a/lib/static/css/main.css b/lib/static/css/main.css index 3fbe2e6a23..5cdf47a1aa 100644 --- a/lib/static/css/main.css +++ b/lib/static/css/main.css @@ -1876,3 +1876,6 @@ footer .copyright { color: rgba(255, 255, 255, 0.4); text-align: center; } +.algolia-autocomplete { + bottom: 10px; +} From 523d824651112ffef3344efd8c734107618955c5 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Sun, 16 Jul 2017 20:34:26 -0700 Subject: [PATCH 05/16] Fix translation functionality to properly condense whitespace and parse escaped characters (#17) --- lib/server/translate-plugin.js | 2 +- lib/server/translate.js | 15 ++++++++++++++- lib/write-translations.js | 4 +++- 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/lib/server/translate-plugin.js b/lib/server/translate-plugin.js index cfadac8ca1..21bbbbf921 100644 --- a/lib/server/translate-plugin.js +++ b/lib/server/translate-plugin.js @@ -19,7 +19,7 @@ module.exports = function translatePlugin(babel) { return; } /* assume translate element only has one child which is the text */ - const text = path.node.children[0].value.trim(); + const text = path.node.children[0].value.trim().replace(/\s+/g, " "); let description = "no description given"; const attributes = path.node.openingElement.attributes; for (let i = 0; i < attributes.length; i++) { diff --git a/lib/server/translate.js b/lib/server/translate.js index 1ec08f3581..ac40dfc355 100644 --- a/lib/server/translate.js +++ b/lib/server/translate.js @@ -11,12 +11,25 @@ const translation = require("./translation.js"); let language = "en"; +/* handle escaped characters that get converted into json strings */ +function parseEscapeSequences(str) { + return str + .replace(new RegExp("\\\\n", "g"), "\n") + .replace(new RegExp("\\\\b", "g"), "\b") + .replace(new RegExp("\\\\f", "g"), "\f") + .replace(new RegExp("\\\\r", "g"), "\r") + .replace(new RegExp("\\\\t", "g"), "\t") + .replace(new RegExp("\\\\'", "g"), "'") + .replace(new RegExp('\\\\"', "g"), '"') + .replace(new RegExp("\\\\", "g"), "\\"); +} + function setLanguage(lang) { language = lang; } function translate(str) { - return translation[language]["pages-strings"][str]; + return parseEscapeSequences(translation[language]["pages-strings"][str]); } module.exports = { diff --git a/lib/write-translations.js b/lib/write-translations.js index 7dff6ff650..84e6ed5cd5 100644 --- a/lib/write-translations.js +++ b/lib/write-translations.js @@ -73,7 +73,9 @@ function execute() { path.node.type === "JSXElement" && path.node.openingElement.name.name === "translate" ) { - const text = path.node.children[0].value.trim(); + const text = path.node.children[0].value + .trim() + .replace(/\s+/g, " "); let description = "no description given"; const attributes = path.node.openingElement.attributes; for (let i = 0; i < attributes.length; i++) { From 704897fd61bb7cacf849d204baed71b59d9dfe17 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 17 Jul 2017 10:35:43 -0700 Subject: [PATCH 06/16] Add config option to allow disabled header title --- examples/siteConfig.js | 1 + lib/core/nav/HeaderNav.js | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/examples/siteConfig.js b/examples/siteConfig.js index f5dcc7f1cf..36d5a7b107 100644 --- a/examples/siteConfig.js +++ b/examples/siteConfig.js @@ -48,6 +48,7 @@ const siteConfig = { ], /* path to images for header/footer */ headerIcon: "img/docusaurus.svg", + disableHeaderTitle: false /* disable title text in header (only show headerIcon) */, footerIcon: "img/docusaurus.svg", favicon: "img/favicon.png", /* default link for docsSidebar */ diff --git a/lib/core/nav/HeaderNav.js b/lib/core/nav/HeaderNav.js index ba86bbf263..e01ae1ee40 100644 --- a/lib/core/nav/HeaderNav.js +++ b/lib/core/nav/HeaderNav.js @@ -113,9 +113,10 @@ class HeaderNav extends React.Component {
-

- {this.props.title} -

+ {!this.props.config.disableHeaderTitle && +

+ {this.props.title} +

} {this.renderResponsiveNav()}
From eccbc178e5f2c50be67a82e35f9a97a0679a58ce Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 17 Jul 2017 10:57:08 -0700 Subject: [PATCH 07/16] Add optional sidebar_title docs front matter field for sidebar titles distinct from document article titles --- examples/example-docs/en/doc1.md | 1 + lib/core/nav/SideNav.js | 20 ++++++++++++++------ lib/write-translations.js | 6 +++++- 3 files changed, 20 insertions(+), 7 deletions(-) diff --git a/examples/example-docs/en/doc1.md b/examples/example-docs/en/doc1.md index 8f2fd96029..9b17145a73 100644 --- a/examples/example-docs/en/doc1.md +++ b/examples/example-docs/en/doc1.md @@ -1,6 +1,7 @@ --- id: doc1 title: Docusaurus +sidebar_title: Docusaurus Guide layout: docs category: Docusaurus permalink: docs/en/doc1.html diff --git a/lib/core/nav/SideNav.js b/lib/core/nav/SideNav.js index 2ea8576642..04bcddd338 100644 --- a/lib/core/nav/SideNav.js +++ b/lib/core/nav/SideNav.js @@ -69,12 +69,20 @@ class SideNav extends React.Component { return categoryString; } getLocalizedString(metadata) { - let localizedString = translation[this.props.language] - ? translation[this.props.language]["localized-strings"][ - metadata.localized_id - ] || metadata.title - : metadata.title; - + let localizedString; + if (metadata.sidebar_title) { + localizedString = translation[this.props.language] + ? translation[this.props.language]["localized-strings"][ + metadata.sidebar_title + ] || metadata.sidebar_title + : metadata.sidebar_title; + } else { + localizedString = translation[this.props.language] + ? translation[this.props.language]["localized-strings"][ + metadata.localized_id + ] || metadata.title + : metadata.title; + } return localizedString; } getLink(metadata) { diff --git a/lib/write-translations.js b/lib/write-translations.js index 84e6ed5cd5..4bd7e711a1 100644 --- a/lib/write-translations.js +++ b/lib/write-translations.js @@ -47,6 +47,11 @@ function execute() { translations["localized-strings"][metadata.id] = metadata.title; translations["localized-strings"][metadata.category] = metadata.category; + + if (metadata.sidebar_title) { + translations["localized-strings"][metadata.sidebar_title] = + metadata.sidebar_title; + } } }); /* look through header links for text to translate */ @@ -89,7 +94,6 @@ function execute() { }); } }); - writeFileAndCreateFolder(CWD + "/i18n/en.json", JSON.stringify(translations)); } From 14ce8c6d30e3833c952583f142c00f45a44369ce Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 17 Jul 2017 11:23:03 -0700 Subject: [PATCH 08/16] Make SideNav.js more readable --- lib/core/nav/SideNav.js | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/lib/core/nav/SideNav.js b/lib/core/nav/SideNav.js index 04bcddd338..3ab9b04ec3 100644 --- a/lib/core/nav/SideNav.js +++ b/lib/core/nav/SideNav.js @@ -70,17 +70,16 @@ class SideNav extends React.Component { } getLocalizedString(metadata) { let localizedString; - if (metadata.sidebar_title) { - localizedString = translation[this.props.language] - ? translation[this.props.language]["localized-strings"][ - metadata.sidebar_title - ] || metadata.sidebar_title - : metadata.sidebar_title; + const i18n = translation[this.props.language]; + const sbTitle = metadata.sidebar_title; + + if (sbTitle) { + localizedString = i18n + ? i18n["localized-strings"][sbTitle] || sbTitle + : sbTitle; } else { - localizedString = translation[this.props.language] - ? translation[this.props.language]["localized-strings"][ - metadata.localized_id - ] || metadata.title + localizedString = i18n + ? i18n["localized-strings"][metadata.localized_id] || metadata.title : metadata.title; } return localizedString; From c6bdc813761779e55e9c0b639d257156b758eabf Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 17 Jul 2017 11:46:35 -0700 Subject: [PATCH 09/16] Add Recent Posts button at bottom of blog posts --- lib/core/BlogPostLayout.js | 8 ++++++++ lib/static/css/main.css | 11 +++++++++++ 2 files changed, 19 insertions(+) diff --git a/lib/core/BlogPostLayout.js b/lib/core/BlogPostLayout.js index fe713e4030..f6d34d9c15 100644 --- a/lib/core/BlogPostLayout.js +++ b/lib/core/BlogPostLayout.js @@ -40,6 +40,14 @@ class BlogPostLayout extends React.Component { config={this.props.config} /> + diff --git a/lib/static/css/main.css b/lib/static/css/main.css index 3fbe2e6a23..6018b9c308 100644 --- a/lib/static/css/main.css +++ b/lib/static/css/main.css @@ -1554,6 +1554,17 @@ table tr th { overflow: hidden; width: 70px; } +.blog-recent-bar { + margin: 20px 0; +} +.blog-recent { + float: left; +} +@media only screen and (min-device-width: 360px) and (max-device-width: 736px) { + .blog-recent-bar { + height: 40px; + } +} .header-link { position: absolute; From 8f705fcb7e06f7e24509a3e339865ed24539684c Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 17 Jul 2017 11:54:28 -0700 Subject: [PATCH 10/16] Move location in css file of search bar css change --- lib/static/css/main.css | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/static/css/main.css b/lib/static/css/main.css index 5cdf47a1aa..64a86d591f 100644 --- a/lib/static/css/main.css +++ b/lib/static/css/main.css @@ -1187,6 +1187,9 @@ ul#languages li { color: #fff; } } +.algolia-autocomplete { + bottom: 10px; +} .docs-prevnext { margin: 20px 0; @@ -1876,6 +1879,3 @@ footer .copyright { color: rgba(255, 255, 255, 0.4); text-align: center; } -.algolia-autocomplete { - bottom: 10px; -} From 2585dfa1f9d731a7c17796ddfcb59a0153e28e72 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 17 Jul 2017 12:25:36 -0700 Subject: [PATCH 11/16] Skip processing any docs with empty/no front matter instead of throwing error --- lib/server/generate.js | 3 +++ lib/server/readMetadata.js | 6 ++++++ 2 files changed, 9 insertions(+) diff --git a/lib/server/generate.js b/lib/server/generate.js index 426bf7f323..8aec19a45c 100644 --- a/lib/server/generate.js +++ b/lib/server/generate.js @@ -106,6 +106,9 @@ function execute() { if (extension === ".md" || extension === ".markdown") { const result = readMetadata.processMetadata(file); + if (!result) { + return; + } const metadata = result.metadata; let rawContent = result.rawContent; diff --git a/lib/server/readMetadata.js b/lib/server/readMetadata.js index c07465727f..521f267624 100644 --- a/lib/server/readMetadata.js +++ b/lib/server/readMetadata.js @@ -60,6 +60,9 @@ function extractMetadata(content) { function processMetadata(file) { const result = extractMetadata(fs.readFileSync(file, "utf8")); + if (!result.metadata || !result.rawContent) { + return null; + } const regexSubFolder = /docs\/(.*)\/.*/; @@ -120,6 +123,9 @@ function generateDocsMetadata() { if (extension === ".md" || extension === ".markdown") { const res = processMetadata(file); + if (!res) { + return; + } const metadata = res.metadata; metadatas.push(metadata); } From de088ce3767a23ad6edb56d49fe4a75754cb23ee Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 17 Jul 2017 16:18:14 -0700 Subject: [PATCH 12/16] Update css blog button styles --- lib/core/BlogPostLayout.js | 4 ++-- lib/static/css/main.css | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/core/BlogPostLayout.js b/lib/core/BlogPostLayout.js index f6d34d9c15..6053eba35c 100644 --- a/lib/core/BlogPostLayout.js +++ b/lib/core/BlogPostLayout.js @@ -40,9 +40,9 @@ class BlogPostLayout extends React.Component { config={this.props.config} /> -
+
Recent Posts diff --git a/lib/static/css/main.css b/lib/static/css/main.css index 6018b9c308..f53f1a6fa7 100644 --- a/lib/static/css/main.css +++ b/lib/static/css/main.css @@ -1554,14 +1554,14 @@ table tr th { overflow: hidden; width: 70px; } -.blog-recent-bar { +.blog-recent { margin: 20px 0; } -.blog-recent { +.blog-recent > a { float: left; } @media only screen and (min-device-width: 360px) and (max-device-width: 736px) { - .blog-recent-bar { + .blog-recent { height: 40px; } } From 35a4b633964db9f65850432c9bfc5d6283817e77 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 17 Jul 2017 17:00:20 -0700 Subject: [PATCH 13/16] Publish changes to npm --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index fadf9b714b..903ef374bb 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,7 @@ "shelljs": "^0.7.8" }, "name": "docusaurus", - "version": "1.0.0-alpha.15", + "version": "1.0.0-alpha.16", "bin": { "docusaurus-start": "./lib/start-server.js", "docusaurus-build": "./lib/build-files.js", From 610b598827b9866f5ea7b32cab81df19af56a8b0 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Tue, 18 Jul 2017 11:44:19 -0700 Subject: [PATCH 14/16] Update start-server.js to ignore .babelrc files --- lib/start-server.js | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/start-server.js b/lib/start-server.js index 857de12aa3..cc0b5a5970 100644 --- a/lib/start-server.js +++ b/lib/start-server.js @@ -11,6 +11,7 @@ require("babel-register")({ ignore: false, + babelrc: false, plugins: [require("./server/translate-plugin.js")], presets: ["react"] }); From 63c62f1d11bdc750a1a0ca6dd785a39ad5e256dc Mon Sep 17 00:00:00 2001 From: Frank Li Date: Tue, 18 Jul 2017 11:44:44 -0700 Subject: [PATCH 15/16] Update build-files.js to ignore .babelrc file --- lib/build-files.js | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/build-files.js b/lib/build-files.js index bcc149e8b6..5d8c5e47fe 100644 --- a/lib/build-files.js +++ b/lib/build-files.js @@ -11,6 +11,7 @@ require("babel-register")({ ignore: false, + babelrc: false, plugins: [require("./server/translate-plugin.js")], presets: ["react"] }); From 7fb1f147fbdde5760943069a875a6ee4786d1402 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Tue, 18 Jul 2017 12:03:42 -0700 Subject: [PATCH 16/16] Update package.json --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 903ef374bb..4f380f1df6 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,7 @@ "shelljs": "^0.7.8" }, "name": "docusaurus", - "version": "1.0.0-alpha.16", + "version": "1.0.0-alpha.17", "bin": { "docusaurus-start": "./lib/start-server.js", "docusaurus-build": "./lib/build-files.js",