From 68ca885f5ba04f3cbd123538ff560359787ef528 Mon Sep 17 00:00:00 2001 From: Yangshun Tay Date: Thu, 30 May 2019 23:07:38 -0700 Subject: [PATCH] v1.11.0 (#1534) --- CHANGELOG.md | 25 +++++-- packages/docusaurus-1.x/package.json | 2 +- packages/docusaurus-init-1.x/package.json | 2 +- website-1.x/package.json | 36 +++++----- .../version-1.11.0/guides-custom-pages.md | 71 +++++++++++++++++++ website-1.x/versions.json | 1 + 6 files changed, 113 insertions(+), 24 deletions(-) create mode 100644 website-1.x/versioned_docs/version-1.11.0/guides-custom-pages.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 72a7fa7dfb60..a314718defc6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a ## [Unreleased] +## [1.11.0] - 2019-05-30 + +We added a new feature of highlighting the table of contents on the right side as you scroll the docs pages. A few bugs affecting local development were also fixed. More notably, the blog's left sidebar will not hide the post titles when `docsSideNavCollapsible` is turned on. This is a bugfix/backward-incompatible change depending on how you view it, but probably nobody wanted that collapsing behavior on the blog sidebar. + +We also welcome @wgao19 to the core team! She'll be helping us with Docusaurus 2 work leveraging on her experience writing documentation and CSS! + +### Changes + +- fix: reload siteConfig.js automatically when locally served page is refreshed ([#1509](https://github.com/facebook/Docusaurus/pull/1509)) +- fix: don't collapse the blog navigation even if collapsible is true ([#1519](https://github.com/facebook/Docusaurus/pull/1519)) +- fix: enable live reloading title of doc ([#1507](https://github.com/facebook/Docusaurus/pull/1507)) +- feat: highlight nav item in onPageNav ToC ([#1524](https://github.com/facebook/Docusaurus/pull/1524)) + ## [1.10.0] - 2019-05-21 This version mainly include many bug fixes and a new feature to use different `host` other than `localhost` through CLI flag. @@ -79,6 +92,7 @@ We accidentally published 2.0.0-alpha.5 as latest on npm. Please do not use that This version mainly include bug fixes and a new feature to skip the next release documents when versioning is enabled. Thank you to the following contributors: + - @yangshun - @endiliey - @vikrantsinghthakur @@ -89,9 +103,10 @@ Thank you to the following contributors: - feat: Add --skip-next-release option to yarn build ([#1292](https://github.com/facebook/Docusaurus/pull/1292)) - fix: handle case insensitive table of contents token ([#1288](https://github.com/facebook/Docusaurus/pull/1288)) - fix: anchors links for underscore character ([#1309](https://github.com/facebook/Docusaurus/pull/1309)) -- fix: autogenerated versions.js should not be confusing ([#1314](https://github.com/facebook/Docusaurus/pull/1314)) +- fix: autogenerated versions.js should not be confusing ([#1314](https://github.com/facebook/Docusaurus/pull/1314)) ### Internal + - Change Docusaurus landing page ([#1290](https://github.com/facebook/Docusaurus/pull/1290)) - We restructured our repository as a monorepo ([#1297](https://github.com/facebook/Docusaurus/pull/1297)) - We folded docusaurus versions (e.g: 1.1.0, 1.1.1, 1.1.2 -> 1.1.x) ([#1313](https://github.com/facebook/Docusaurus/pull/1313)) @@ -214,6 +229,7 @@ Hotfix for 1.6.1. We overlooked a critical bug caused by hardcoded path on PR [# This version mainly includes bug fixes found in 1.6.0 that improves stability. Thank you to the following contributors who helped with this release: + - @endiliey - @jakebolam - @JoelMarcey @@ -231,7 +247,6 @@ Thank you to the following contributors who helped with this release: - Allow custom commit message for publish-gh-pages ([#1136](https://github.com/facebook/Docusaurus/pull/1136)) - ## [1.6.0] - 2018-12-1 This releases includes few bug fixes and features. One notable feature allows user to change/remove `docs` prefix from the generated docusaurus URL. @@ -262,7 +277,8 @@ Thank you to the following contributors who helped with this release: - Fix docusaurus-version not working for subcategory in sidebar ([#1124](https://github.com/facebook/Docusaurus/pull/1124)) - Fix docusaurus-version to allow duplicate id in different subdirectory ([#1125](https://github.com/facebook/Docusaurus/pull/1125)) -## Docs +## Docs + - Add guide on setting custom docs path ([#1098](https://github.com/facebook/Docusaurus/pull/1098)) - Document that `website` folder can be renamed ([#1106](https://github.com/facebook/Docusaurus/pull/1106)) - Specify markdown flavor ([#1118](https://github.com/facebook/Docusaurus/pull/1118)) @@ -1104,7 +1120,8 @@ N/A - Blog - Documentation -[unreleased]: https://github.com/facebook/Docusaurus/compare/v1.10.0...HEAD +[unreleased]: https://github.com/facebook/Docusaurus/compare/v1.11.0...HEAD +[1.11.0]: https://github.com/facebook/Docusaurus/compare/v1.10.0...v1.11.0 [1.10.0]: https://github.com/facebook/Docusaurus/compare/v1.9.0...v1.10.0 [1.9.0]: https://github.com/facebook/Docusaurus/compare/v1.8.1...v1.9.0 [1.8.1]: https://github.com/facebook/Docusaurus/compare/v1.8.0...v1.8.1 diff --git a/packages/docusaurus-1.x/package.json b/packages/docusaurus-1.x/package.json index c7239592b0b8..d35e1f73bfef 100644 --- a/packages/docusaurus-1.x/package.json +++ b/packages/docusaurus-1.x/package.json @@ -1,7 +1,7 @@ { "name": "docusaurus", "description": "Easy to Maintain Open Source Documentation Websites", - "version": "2.0.0-alpha.18", + "version": "1.11.0", "license": "MIT", "keywords": [ "documentation", diff --git a/packages/docusaurus-init-1.x/package.json b/packages/docusaurus-init-1.x/package.json index 3215bde3ace2..214be07abb6b 100644 --- a/packages/docusaurus-init-1.x/package.json +++ b/packages/docusaurus-init-1.x/package.json @@ -1,7 +1,7 @@ { "name": "docusaurus-init", "description": "Initialization script for Docusaurus", - "version": "2.0.0-alpha.18", + "version": "1.11.0", "license": "MIT", "preferGlobal": true, "keywords": [ diff --git a/website-1.x/package.json b/website-1.x/package.json index d30d549162b3..436b03881b63 100644 --- a/website-1.x/package.json +++ b/website-1.x/package.json @@ -1,20 +1,20 @@ { - "name": "docusaurus-1-website", - "version": "2.0.0-alpha.18", - "private": true, - "scripts": { - "start": "docusaurus-start", - "build": "docusaurus-build", - "publish-gh-pages": "docusaurus-publish", - "examples": "docusaurus-examples", - "write-translations": "docusaurus-write-translations", - "docusaurus-version": "docusaurus-version", - "rename-version": "docusaurus-rename-version", - "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master", - "crowdin-download": "crowdin --config ../crowdin.yaml download -b master" - }, - "dependencies": { - "async": "^2.5.0", - "docusaurus": "^2.0.0-alpha.18" - } + "name": "docusaurus-1-website", + "version": "2.0.0-alpha.18", + "private": true, + "scripts": { + "start": "docusaurus-start", + "build": "docusaurus-build", + "publish-gh-pages": "docusaurus-publish", + "examples": "docusaurus-examples", + "write-translations": "docusaurus-write-translations", + "docusaurus-version": "docusaurus-version", + "rename-version": "docusaurus-rename-version", + "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master", + "crowdin-download": "crowdin --config ../crowdin.yaml download -b master" + }, + "dependencies": { + "async": "^2.5.0", + "docusaurus": "^1.11.0" + } } diff --git a/website-1.x/versioned_docs/version-1.11.0/guides-custom-pages.md b/website-1.x/versioned_docs/version-1.11.0/guides-custom-pages.md new file mode 100644 index 000000000000..a3ad707cd827 --- /dev/null +++ b/website-1.x/versioned_docs/version-1.11.0/guides-custom-pages.md @@ -0,0 +1,71 @@ +--- +id: version-1.11.0-custom-pages +title: Custom Pages +original_id: custom-pages +--- + +You can add pages to your site that are not part of the standard docs or blog markdown files. You can do this by adding `.js` files to the `website/pages` directory. These files are [React](https://reactjs.org/) components and the `render()` is called to create them, backed by CSS classes, etc. + +## Customizing Your Home Page + +The easiest way to get started customizing your home page is to use the example site that was [created](getting-started-site-creation.md) when you ran the [Docusaurus initialization script](getting-started-installation.md). + +You can [start](getting-started-preparation.md#verifying-installation) your local server and go to `http://localhost:3000` to see what the example home page looks like. From there, edit the `website/pages/en/index.js` file and its various components to use the images and text you want for your project. + +## Adding Other Custom Pages + +Docusaurus provides some simple example pages in the `website/pages/en` directory, including `index.js`, `users.js`, and `help.js`. These are good examples to showcase how to create a custom page for Docusaurus. + +```bash +root-directory +├── docs +└── website + ├── blog + ├── core + │ └── Footer.js + ├── package.json + ├── pages + │ └── en + │ ├── help.js + │ ├── index.js + │ └── users.js + ├── sidebars.json + ├── siteConfig.js + └── static +``` + +Of course, you are also free to write your own pages. It is strongly suggested that you at least have an index page, but none of the pages provided are mandatory to include in your site. More information on how to use the provided components or include your own can be found [here](api-pages.md). Information on how to link to your different pages in the header navigation bar can be found [here](guides-navigation.md). + +> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`, + +## Adding Static Pages + +Static `.html` files can also be used, but they will not include Docusaurus' header, footer, or styles by default. These can be added to the `static` directory in the same way as other [static assets](api-pages.md#using-static-assets). Alternatively, they can be placed in the `pages` directory and would be served as-is instead of being rendered from React. + +If you wish to use Docusaurus' stylesheet, you can access it at `${baseUrl}css/main.css`. If you wish to use separate CSS for these static pages, you can exclude them from being concatenated to Docusaurus' styles by adding them into the `siteConfig.separateCss` field in `siteConfig.js`. + +> You can set the [`$wrapPagesHTML` site config option](api-site-config.md#optional-fields) in order to wrap raw HTML fragments with the Docusaurus site styling, header and footer. + +## Customizing Your Site Footer + +Starting from the example `core/Footer.js` file that was [created](getting-started-site-creation.md) when you ran the [Docusaurus initialization script](getting-started-installation.md), edit the footer to include any links to pages on your site or other sites that you wish to have. + +The example provided has three columns with a footer image on the left and Facebook's open source logo and copyright at the bottom. If your project is not a Facebook open source project, remove the logo and copyright. Otherwise, feel free to get creative with your footer and make it look however you'd like! + +Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc. + +Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static HTML pages you include. + +If you do not want a footer for your site, change the `render` function of `core/Footer.js` to return `null`. e.g., + +```jsx +const React = require('react'); + +class Footer extends React.Component { + render() { + return null; + } +} + +module.exports = Footer; +``` diff --git a/website-1.x/versions.json b/website-1.x/versions.json index 16ed90cd1b12..ee45790ad29c 100644 --- a/website-1.x/versions.json +++ b/website-1.x/versions.json @@ -1,4 +1,5 @@ [ + "1.11.0", "1.10.0", "1.9.0", "1.8.1",