Skip to content

Commit

Permalink
Allow the docs not to just be in a folder called docs
Browse files Browse the repository at this point in the history
Also:
- regex escaping
- update api documentation
  • Loading branch information
JoelMarcey committed Nov 9, 2017
1 parent dc0c139 commit e273dfc
Show file tree
Hide file tree
Showing 5 changed files with 25 additions and 9 deletions.
10 changes: 10 additions & 0 deletions docs/api-site-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,16 @@ headerLinks: [

### Optional Fields

`customDocsPath` - By default, Docusaurus expects your documentation to be in a directory called `docs`. This directory is at the same level as the `website` directory (i.e., not inside the `website` directory). You can specify a custom path to your documentation with this field. **Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories**.

```js
customDocsPath: "docs/site"
```

```js
customDocsPath: "website-docs"
```

`editUrl` - url for editing docs, usage example: `editUrl + 'en/doc1.md'`. If this field is omitted, there will be no "Edit this Doc" button for each document.

`users` - The `users` array mentioned earlier.
Expand Down
10 changes: 6 additions & 4 deletions lib/core/nav/HeaderNav.js
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ let versions;
if (ENABLE_VERSIONING) {
versions = require(CWD + "/versions.json");
}
require("../../server/readMetadata.js").generateMetadataDocs();
const readMetadata = require("../../server/readMetadata.js");
readMetadata.generateMetadataDocs();
const Metadata = require("../metadata.js");

// language dropdown nav item for when translations are enabled
Expand Down Expand Up @@ -221,17 +222,18 @@ class HeaderNav extends React.Component {
}
let search = false;
headerLinks.forEach(link => {
if (link.doc && !fs.existsSync(CWD + "/../docs/")) {
if (link.doc && !fs.existsSync(CWD + "/../" + readMetadata.getDocsPath() + "/")) {
throw new Error(
"You have 'doc' in your headerLinks, but no 'docs' folder exists one level up from " +
"You have 'doc' in your headerLinks, but no '" + readMetadata.getDocsPath() +
"' folder exists one level up from " +
"'website' folder. Did you run `docusaurus-init` or `npm run examples`? If so, " +
"make sure you rename 'docs-examples-from-docusaurus' to 'docs'."
);
}
if (link.blog && !fs.existsSync(CWD + "/blog/")) {
throw new Error(
"You have 'blog' in your headerLinks, but no 'blog' folder exists in your " +
"website folder. Did you run `docusaurus-init` or `npm run examples`? If so, " +
"'website' folder. Did you run `docusaurus-init` or `npm run examples`? If so, " +
"make sure you rename 'blog-examples-from-docusaurus' to 'blog'."
);
}
Expand Down
11 changes: 7 additions & 4 deletions lib/server/readMetadata.js
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ const glob = require("glob");
const chalk = require("chalk");
const siteConfig = require(CWD + "/siteConfig.js");
const versionFallback = require("./versionFallback.js");
const escapeStringRegexp = require("escape-string-regexp");

const ENABLE_VERSIONING = fs.existsSync(CWD + "/versions.json");

Expand All @@ -31,13 +32,15 @@ if (fs.existsSync(CWD + "/languages.js")) {
];
}

// Can add additional path information to the docs folder
// Can have a custom docs path. Top level folder still needs to be in directory
// at the same level as `website`, not inside `website`.
// e.g., docs/whereDocsReallyExist
// website-docs/
// All .md docs still (currently) must be in one flat directory hierarchy.
// e.g., docs/whereDocsReallyExist/*.md (all .md files in this dir)
function getDocsPath() {
return siteConfig.docsAdditionalPath
? "docs" + siteConfig.docsAdditionalPath
return siteConfig.customDocsPath
? siteConfig.customDocsPath
: "docs";
}
// returns map from id to object containing sidebar ordering info
Expand Down Expand Up @@ -125,7 +128,7 @@ function extractMetadata(content) {
function processMetadata(file) {
const result = extractMetadata(fs.readFileSync(file, "utf8"));

let regexSubFolder = new RegExp("/" + getDocsPath() + "\/(.*)\/.*/");
let regexSubFolder = new RegExp("/" + escapeStringRegexp(getDocsPath()) + "\/(.*)\/.*/");

let language = "en";
const match = regexSubFolder.exec(file);
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
"commander": "^2.11.0",
"crowdin-cli": "^0.3.0",
"diff": "^3.3.0",
"escape-string-regexp": "^1.0.5",
"express": "^4.15.3",
"feed": "^1.1.0",
"fs-extra": "^3.0.1",
Expand Down
2 changes: 1 addition & 1 deletion website/siteConfig.js
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ const siteConfig = {
copyright: "Copyright © " + new Date().getFullYear() + " Facebook Inc.",
highlight: {
theme: "solarized-dark"
}
},
};


Expand Down

0 comments on commit e273dfc

Please sign in to comment.