Merge remote-tracking branch 'upstream/master' into blog

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 .vscode
+.idea
 *.code-workspace
 
 node_modules

README.md

@@ -1,4 +1,18 @@
-# [Docusaurus](https://docusaurus.io) · [![npm version](https://img.shields.io/npm/v/docusaurus.svg?style=flat)](https://www.npmjs.com/package/docusaurus) [![CircleCI Status](https://circleci.com/gh/facebook/Docusaurus.svg?style=shield)](https://circleci.com/gh/facebook/Docusaurus) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md#pull-requests)
+<h1 align="center">
+ <p align="center">Docusaurus</p>
+ <a href="https://docusaurus.io"><img src="/website/static/img/slash-introducing.png" alt="Docusaurus"></a>
+</h1>
+
+<p align="center">
+ <a href="https://www.npmjs.com/package/docusaurus"><img src="https://img.shields.io/npm/v/docusaurus.svg?style=flat" alt="npm version"></a>
+ <a href="https://circleci.com/gh/facebook/Docusaurus"><img src="https://circleci.com/gh/facebook/Docusaurus.svg?style=shield" alt="CircleCI Status"></a>
+ <a href="CONTRIBUTING.md#pull-requests"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
+ <a href="https://discord.gg/docusaurus"><img src="https://img.shields.io/badge/chat-on%20discord-7289da.svg" alt="Chat"></a>
+ <a href="https://github.com/prettier/prettier"><img alt="code style: prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square"></a>
+ <a href="https://github.com/facebook/jest"><img src="https://img.shields.io/badge/tested_with-jest-99424f.svg" alt="Tested with Jest"></a>
+</p>
+
+## Introduction
 
 Docusaurus is a project for easily building, deploying, and maintaining open source project websites.
 

docs/api-site-config.md

@@ -17,7 +17,7 @@ The `siteConfig` object contains the bulk of the configuration settings for your
 
 ### Mandatory Fields
 
-`baseUrl` - baseUrl for your site.
+`baseUrl` - baseUrl for your site. For example, `/pages/org/project/` is the baseUrl of https://git.facebook.com/pages/org/project/
 
 `colors` - Color configurations for the site.
 

docs/guides-navigation.md

@@ -72,6 +72,28 @@ Or you can create a new category within the sidebar:
 }
 ```
 
+However, for a document located in a docs subdirectory like below:
+
+```bash
+docs
+└── dir1
+ └── getting-started.md
+```
+
+You should provide `directory/id` instead of `id` in `sidebars.json`.
+
+```js
+{
+ "docs": {
+ "My New Sidebar Category": [
+ "dir1/getting-started"
+ ],
+ ...
+ },
+ ...
+}
+```
+
 ### Adding New Sidebars
 
 You can also put a document in a new sidebar. In the following example, we are creating an `examples-sidebar` sidebar within `sidebars.json` that has a category called `My Example Category` containing a document with an `id` of `my-examples`.

docs/guides-search.md

@@ -33,7 +33,7 @@ const siteConfig = {
  algolia: { 
  ... 
  algoliaOptions: { 
- facetFilters: [ "lang:LANGUAGE", "version:VERSION" ] 
+ facetFilters: [ "language:LANGUAGE", "version:VERSION" ] 
  } 
  }, 
 }; 

lib/server/__tests__/__fixtures__/doc1.md

@@ -3,4 +3,19 @@ id: doc1
 title: Document 1
 ---
 
-Docusaurus is the best :)
+Docusaurus is the best :)
+
+![image1](assets/image1.png)
+
+```js
+console.log("Docusaurus");
+```
+
+![image2](assets/image2.jpg)
+![image3](assets/image3.gif)
+
+Don't replace the one below
+```md
+
+![image4](assets/image4.bmp)
+```

lib/server/__tests__/__fixtures__/doc2.md

@@ -15,4 +15,15 @@ title: Document 2
 ## Repeating Docs
 
 - [doc1](doc1.md)
-- [doc2](./doc2.md)
+- [doc2](./doc2.md)
+
+## Do not replace this
+```md
+![image1](assets/image1.png)
+```
+
+```js
+const doc1 = foo();
+console.log("[image2](assets/image2.jpg)");
+const testStr = `![image3](assets/image3.gif)`;
+```

lib/server/__tests__/__snapshots__/docs.test.js.snap

@@ -2,7 +2,22 @@
 
 exports[`mdToHtmlify transform nothing 1`] = `
 "
-Docusaurus is the best :)"
+Docusaurus is the best :)
+
+![image1](assets/image1.png)
+
+\`\`\`js
+console.log(\\"Docusaurus\\");
+\`\`\`
+
+![image2](assets/image2.jpg)
+![image3](assets/image3.gif)
+
+Don't replace the one below
+\`\`\`md
+
+![image4](assets/image4.bmp)
+\`\`\`"
 `;
 
 exports[`mdToHtmlify transform to correct link 1`] = `
@@ -19,5 +34,64 @@ exports[`mdToHtmlify transform to correct link 1`] = `
 ## Repeating Docs
 
 - [doc1](/docs/en/next/doc1)
-- [doc2](/docs/en/next/doc2)"
+- [doc2](/docs/en/next/doc2)
+
+## Do not replace this
+\`\`\`md
+![image1](assets/image1.png)
+\`\`\`
+
+\`\`\`js
+const doc1 = foo();
+console.log(\\"[image2](assets/image2.jpg)\\");
+const testStr = \`![image3](assets/image3.gif)\`;
+\`\`\`"
+`;
+
+exports[`replaceAssetsLink does not transform document without valid assets link 1`] = `
+"
+### Existing Docs
+
+- [doc1](doc1.md)
+- [doc2](./doc2.md)
+
+### Non-existing Docs
+
+- [hahaha](hahaha.md)
+
+## Repeating Docs
+
+- [doc1](doc1.md)
+- [doc2](./doc2.md)
+
+## Do not replace this
+\`\`\`md
+![image1](assets/image1.png)
+\`\`\`
+
+\`\`\`js
+const doc1 = foo();
+console.log(\\"[image2](assets/image2.jpg)\\");
+const testStr = \`![image3](assets/image3.gif)\`;
+\`\`\`"
+`;
+
+exports[`replaceAssetsLink transform document with valid assets link 1`] = `
+"
+Docusaurus is the best :)
+
+![image1](/docs/assets/image1.png)
+
+\`\`\`js
+console.log(\\"Docusaurus\\");
+\`\`\`
+
+![image2](/docs/assets/image2.jpg)
+![image3](/docs/assets/image3.gif)
+
+Don't replace the one below
+\`\`\`md
+
+![image4](assets/image4.bmp)
+\`\`\`"
 `;

lib/server/__tests__/docs.test.js

@@ -49,9 +49,10 @@ const doc2 = fs.readFileSync(
  'utf8'
 );
 
+const rawContent1 = metadataUtils.extractMetadata(doc1).rawContent;
+const rawContent2 = metadataUtils.extractMetadata(doc2).rawContent;
+
 describe('mdToHtmlify', () => {
- const rawContent1 = metadataUtils.extractMetadata(doc1).rawContent;
- const rawContent2 = metadataUtils.extractMetadata(doc2).rawContent;
  const mdToHtml = metadataUtils.mdToHtml(Metadata, '/');
 
  test('transform nothing', () => {
@@ -129,6 +130,31 @@ describe('getFile', () => {
  });
 });
 
+describe('replaceAssetsLink', () => {
+ test('transform document with valid assets link', () => {
+ const content1 = docs.replaceAssetsLink(rawContent1);
+ expect(content1).toMatchSnapshot();
+ expect(content1).toContain('![image1](/docs/assets/image1.png)');
+ expect(content1).toContain('![image2](/docs/assets/image2.jpg)');
+ expect(content1).toContain('![image3](/docs/assets/image3.gif)');
+ expect(content1).toContain('![image4](assets/image4.bmp)');
+ expect(content1).not.toContain('![image1](assets/image1.png)');
+ expect(content1).not.toContain('![image2](assets/image2.jpg)');
+ expect(content1).not.toContain('![image3](assets/image3.gif)');
+ expect(content1).not.toContain('![image4](/docs/assets/image4.bmp)');
+ expect(content1).not.toEqual(rawContent1);
+ });
+
+ test('does not transform document without valid assets link', () => {
+ const content2 = docs.replaceAssetsLink(rawContent2);
+ expect(content2).toMatchSnapshot();
+ expect(content2).not.toContain('![image1](/docs/assets/image1.png)');
+ expect(content2).not.toContain('![image2](/docs/assets/image2.jpg)');
+ expect(content2).not.toContain('![image3](/docs/assets/image3.gif)');
+ expect(content2).toEqual(rawContent2);
+ });
+});
+
 afterAll(() => {
  process.chdir(originalCwd);
 });

lib/server/docs.js

@@ -70,18 +70,28 @@ function mdToHtmlify(oldContent, mdToHtml, metadata) {
  return content;
 }
 
+function replaceAssetsLink(oldContent) {
+ let fencedBlock = false;
+ const lines = oldContent.split('\n').map(line => {
+ if (line.trim().startsWith('```')) {
+ fencedBlock = !fencedBlock;
+ }
+ return fencedBlock
+ ? line
+ : line.replace(/\]\(assets\//g, `](${siteConfig.baseUrl}docs/assets/`);
+ });
+ return lines.join('\n');
+}
+
 function getStr(rawContent, mdToHtml, metadata) {
  // generate table of contents
  let content = insertTOC(rawContent);
 
  // replace any links to markdown files to their website html links
  content = mdToHtmlify(content, mdToHtml, metadata);
 
- // replace any relative links to static assets to absolute links
- content = content.replace(
- /\]\(assets\//g,
- `](${siteConfig.baseUrl}docs/assets/`
- );
+ // replace any relative links to static assets (not in fenced code blocks) to absolute links
+ content = replaceAssetsLink(content);
 
  const DocsLayout = require('../core/DocsLayout.js');
  return renderToStaticMarkupWithDoctype(
@@ -118,4 +128,5 @@ module.exports = {
  getFile,
  getRedirectStr,
  mdToHtmlify,
+ replaceAssetsLink,
 };

website/siteConfig.js

@@ -37,7 +37,7 @@ const siteConfig = {
  apiKey: '3eb9507824b8be89e7a199ecaa1a9d2c',
  indexName: 'docusaurus',
  algoliaOptions: {
- facetFilters: ['lang:LANGUAGE'],
+ facetFilters: ['language:LANGUAGE', 'version:VERSION'],
  },
  },
  colors: {

website/versioned_docs/version-1.2.0/guides-navigation.md

@@ -73,6 +73,28 @@ Or you can create a new category within the sidebar:
 }
 ```
 
+However, for a document located in a docs subdirectory like below:
+
+```bash
+docs
+└── dir1
+ └── getting-started.md
+```
+
+You should provide `directory/id` instead of `id` in `sidebars.json`.
+
+```js
+{
+ "docs": {
+ "My New Sidebar Category": [
+ "dir1/getting-started"
+ ],
+ ...
+ },
+ ...
+}
+```
+
 ### Adding New Sidebars
 
 You can also put a document in a new sidebar. In the following example, we are creating an `examples-sidebar` sidebar within `sidebars.json` that has a category called `My Example Category` containing a document with an `id` of `my-examples`.