mirror of
https://github.com/facebook/docusaurus.git
synced 2025-12-26 01:33:02 +00:00
Publish v1.3.0 (#791)
* Publish v1.3.0 * Run version script * Update CHANGELOG.md
This commit is contained in:
Yangshun Tay
GitHub
parent
1094dbd352
commit
82f5727965
38
CHANGELOG.md
38
CHANGELOG.md
|
|
@ -6,6 +6,41 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
## [1.3.0] - 2018-06-20
|
||||
|
||||
1.3.0 introduces a brief clean up of our CSS, overall site typography and some improvements to Algolia search.
|
||||
|
||||
Welcome to our newest user, [ml5](https://ml5js.org/), a really cool machine library in JavaScript.
|
||||
|
||||
Thank you to the following contributors who helped with this release:
|
||||
|
||||
- @endiliey
|
||||
- @JoelMarcey
|
||||
- @yangshun
|
||||
|
||||
### Breaking changes
|
||||
|
||||
- Since we made some CSS changes, there's a good chance it might not be compatible with your custom CSS if you have any. We recommend that you audit each page of the site for any UI issues caused by this change. We'll try to minimize such backward-incompatible CSS changes in future.
|
||||
- Other UI changes include:
|
||||
- Left sidebar is sticky by default on supported browsers. We saw many of our users write custom CSS for that behavior and decided to incorporate it in the core.
|
||||
- Footer is now a darker shade of black for better contrast.
|
||||
- Background color of site changed to `#fff`.
|
||||
- Headers are now black (from `$primaryColor`) and have bolder font weight.
|
||||
- Blockquotes are changed to yellow (from pink).
|
||||
|
||||
### Fixed/Changed
|
||||
|
||||
- The search input will now search the docs in the [correct language](https://github.com/facebook/Docusaurus/commit/df429262429e449e78745423ff2c9ab6c6fd1d5c).
|
||||
- Algolia will be able to scrape multi-language sites better with the introduction of [special meta tags](https://github.com/facebook/Docusaurus/commit/0eb6612b58a6ee93d5de715f87201eb9fabc82c2).
|
||||
|
||||
### Added
|
||||
|
||||
N/A
|
||||
|
||||
### Removed
|
||||
|
||||
N/A
|
||||
|
||||
## [1.2.1] - 2018-06-17
|
||||
|
||||
Fixes from existing issues and those found in the 1.2.0 release. Fixes include being able to modify the metadata of a doc without resorting to deleting `en.json`, using absolute URLs instead of relative for docs links, and more. We also added a few new things as well.
|
||||
|
|
@ -563,7 +598,8 @@ N/A
|
|||
- Blog
|
||||
- Documentation
|
||||
|
||||
[Unreleased]: https://github.com/facebook/Docusaurus/compare/v1.2.1...HEAD
|
||||
[Unreleased]: https://github.com/facebook/Docusaurus/compare/v1.3.0...HEAD
|
||||
[1.3.0]: https://github.com/facebook/Docusaurus/compare/v1.2.1...v1.3.0
|
||||
[1.2.1]: https://github.com/facebook/Docusaurus/compare/v1.2.0...v1.2.1
|
||||
[1.2.0]: https://github.com/facebook/Docusaurus/compare/v1.1.5...v1.2.0
|
||||
[1.1.5]: https://github.com/facebook/Docusaurus/compare/v1.1.4...v1.1.5
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"name": "docusaurus",
|
||||
"description": "Easy to Maintain Open Source Documentation Websites",
|
||||
"version": "1.2.1",
|
||||
"version": "1.3.0",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"documentation",
|
||||
|
|
|
|||
|
|
@ -0,0 +1,209 @@
|
|||
---
|
||||
id: version-1.3.0-doc-markdown
|
||||
title: Markdown Features
|
||||
original_id: doc-markdown
|
||||
---
|
||||
|
||||
Find out more about Docusaurus-specific fields when writing Markdown.
|
||||
|
||||
## Markdown Headers
|
||||
|
||||
### Documents
|
||||
|
||||
Documents use the following markdown header fields that are enclosed by a line `---` on either side:
|
||||
|
||||
`id`: A unique document id. If this field is not present, the document's `id` will default to its file name (without the extension).
|
||||
|
||||
`title`: The title of your document. If this field is not present, the document's `title` will default to its `id`.
|
||||
|
||||
`hide_title`: Whether to hide the title at the top of the doc.
|
||||
|
||||
`sidebar_label`: The text shown in the document sidebar for this document. If this field is not present, the document's `sidebar_label` will default to its `title`.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
---
|
||||
```
|
||||
|
||||
Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
original_id: doc1
|
||||
---
|
||||
```
|
||||
|
||||
`custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from optional fields of `siteConfig.js`. See [siteConfig.js](site-config.md) docs for more information.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
---
|
||||
```
|
||||
|
||||
### Blog Posts
|
||||
|
||||
Blog posts use the following markdown header fields that are enclosed by a line `---` on either side:
|
||||
|
||||
`title`: The title of this blog post.
|
||||
|
||||
`author`: The author of this blog post. If this field is omitted, no author name will be shown.
|
||||
|
||||
`authorURL`: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.
|
||||
|
||||
`authorFBID`: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
authorFBID: 100002976521003
|
||||
---
|
||||
```
|
||||
|
||||
## Extra Features
|
||||
|
||||
Docusaurus supports some extra features when writing documentation in markdown.
|
||||
|
||||
### Linking other Documents
|
||||
|
||||
You can use relative URLs to other documentation files which will automatically get converted to the corresponding HTML links when they get rendered.
|
||||
|
||||
Example:
|
||||
|
||||
```md
|
||||
[This links to another document](other-document.md)
|
||||
```
|
||||
|
||||
This markdown will automatically get converted into a link to `/docs/other-document.html` (or the appropriately translated/versioned link) once it gets rendered.
|
||||
|
||||
This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct HTML links when they get rendered.
|
||||
|
||||
### Linking to Images and Other Assets
|
||||
|
||||
Static assets can be linked to in the same way that documents are, using relative URLs. Static assets used in documents and blogs should go into `docs/assets` and `website/blog/assets`, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.
|
||||
|
||||
Example:
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
### Generating Table of Contents
|
||||
|
||||
You can make an auto-generated list of links, which can be useful as a table of contents for API docs.
|
||||
|
||||
In your markdown file, insert a line with the text <`AUTOGENERATED_TABLE_OF_CONTENTS`>. Write your documentation using `h3` headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <`AUTOGENERATED_TABLE_OF_CONTENTS`>.
|
||||
|
||||
Example:
|
||||
|
||||
```md
|
||||
### `docusaurus.function(a, b)`
|
||||
|
||||
Text describing my function
|
||||
|
||||
### `docdoc(file)`
|
||||
|
||||
Text describing my function
|
||||
```
|
||||
|
||||
will lead to a table of contents of the functions:
|
||||
|
||||
```md
|
||||
- `docusaurus.function(a, b)`
|
||||
- `docdoc(file)`
|
||||
```
|
||||
|
||||
and each function will link to their corresponding sections in the page.
|
||||
|
||||
## Syntax Highlighting
|
||||
|
||||
Syntax highlighting is enabled by default on fenced code blocks. The language should be detected automatically, but you can sometimes get better results by specifying the language. You can do so using an [info string](https://github.github.com/gfm/#example-111), following the three opening backticks. The following JavaScript example...
|
||||
|
||||
```js
|
||||
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
|
||||
```
|
||||
|
||||
...would be rendered with syntax highlighting like so:
|
||||
|
||||
```js
|
||||
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
|
||||
```
|
||||
|
||||
Highlighting is provided by [Highlight.js](https://highlightjs.org) using the theme specified in your `siteConfig.js` file as part of the `highlight` key:
|
||||
|
||||
```js
|
||||
{
|
||||
...
|
||||
highlight: {
|
||||
theme: 'default'
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
You can find the full list of supported themes in the Highlight.js [`styles`](https://github.com/isagalaev/highlight.js/tree/master/src/styles) directory.
|
||||
|
||||
### Registering additional languages
|
||||
|
||||
While Highlight.js provides support for [many popular languages out of the box](https://highlightjs.org/static/demo/), you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the `hljs` constant as part of the `highlight` config key. This in turn allows you to call [`registerLanguage`](http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language):
|
||||
|
||||
```js
|
||||
{
|
||||
...
|
||||
highlight: {
|
||||
theme: 'default',
|
||||
hljs: function(hljs) {
|
||||
hljs.registerLanguage('galacticbasic', function(hljs) {
|
||||
// ...
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using Prism as additional syntax highlighter
|
||||
|
||||
You can also opt to use Prism to syntax highlight certain languages available in the list [here](https://github.com/PrismJS/prism/tree/master/components). Include those languages in `usePrism` field in your [siteConfig.js](api-site-config.md)
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
// siteConfig.js
|
||||
usePrism: ['jsx']
|
||||
```
|
||||
|
||||
Notice that the code block below uses JSX syntax highlighting from Prism.
|
||||
|
||||
```jsx
|
||||
class Example extends React.Component {
|
||||
render() {
|
||||
return (
|
||||
<View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
|
||||
<Text>Docusaurus</Text>
|
||||
<Button
|
||||
title="Click me"
|
||||
onPress={() => this.props.navigation.push('Docusaurus')}
|
||||
/>
|
||||
</View>
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,138 @@
|
|||
---
|
||||
id: version-1.3.0-adding-blog
|
||||
title: Adding a Blog
|
||||
original_id: adding-blog
|
||||
---
|
||||
|
||||
## Initial Setup
|
||||
|
||||
To setup your site's blog, start by creating a `blog` directory within your repo's `website` directory.
|
||||
|
||||
Then, add a header link to your blog within `siteConfig.js`:
|
||||
|
||||
```js
|
||||
headerLinks: [
|
||||
...
|
||||
{ blog: true, label: 'Blog' },
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
## Adding Posts
|
||||
|
||||
To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-My-Blog-Post-Title.md`. The post date is extracted from the file name.
|
||||
|
||||
For example, at `website/blog/2017-08-18-Introducing-Docusaurus.md`:
|
||||
|
||||
```yml
|
||||
---
|
||||
author: Frank Li
|
||||
authorURL: https://twitter.com/foobarbaz
|
||||
authorFBID: 503283835
|
||||
title: Introducing Docusaurus
|
||||
---
|
||||
|
||||
Lorem Ipsum...
|
||||
```
|
||||
|
||||
## Header Options
|
||||
|
||||
The only required field is `title`; however, we provide options to add author information to your blog post as well.
|
||||
|
||||
* `author` - The text label of the author byline.
|
||||
* `authorURL` - The URL associated with the author. This could be a Twitter, GitHub, Facebook account, etc.
|
||||
* `authorFBID` - The Facebook profile ID that is used to fetch the profile picture.
|
||||
* `authorImageURL` - The URL to the author's image. (Note: If you use both `authorFBID` and `authorImageURL`, `authorFBID` will take precedence. Don't include `authorFBID` if you want `authorImageURL` to appear.)
|
||||
* `title` - The blog post title.
|
||||
|
||||
## Summary Truncation
|
||||
|
||||
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Truncation Example
|
||||
---
|
||||
|
||||
All this will be part of the blog post summary.
|
||||
|
||||
Even this.
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
But anything from here on down will not be.
|
||||
|
||||
Not this.
|
||||
|
||||
Or this.
|
||||
```
|
||||
|
||||
## Changing How Many Blog Posts Show on Sidebar
|
||||
|
||||
By default, 5 recent blog posts are shown on the sidebar.
|
||||
|
||||
You can configure a specific amount of blog posts to show by adding a `blogSidebarCount` setting to your `siteConfig.js`.
|
||||
|
||||
The available options are an integer representing the number of posts you wish to show or a string with the value `'ALL'`.
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
blogSidebarCount: 'ALL';
|
||||
```
|
||||
|
||||
## Changing The Sidebar Title
|
||||
|
||||
You can configure a specific sidebar title by adding a `blogSidebarTitle` setting to your `siteConfig.js`.
|
||||
|
||||
The option is an object which can have the keys `default` and `all`. Specifying a value for `default` allows you to change the default sidebar title. Specifying a value for `all` allows you to change the sidebar title when the `blogSidebarCount` option is set to `'ALL'`.
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
blogSidebarTitle: { default: 'Recent posts', all: 'All blog posts' },
|
||||
```
|
||||
|
||||
## RSS Feed
|
||||
|
||||
Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML <HEAD> tag.
|
||||
|
||||
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up 250 characters are used.
|
||||
|
||||
## Social Buttons
|
||||
|
||||
If you want Facebook and/or Twitter social buttons at the bottom of your blog posts, set the `facebookAppId` and/or `twitter` [site configuration](api-site-config.md) options in `siteConfig.js`.
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### I want to run in "Blog Only" mode.
|
||||
|
||||
You can run your Docusaurus site without a landing page and instead have your blog load first.
|
||||
|
||||
To do this:
|
||||
|
||||
1. Create a file `index.html` in `website/static/`.
|
||||
1. Place the contents of the template below into `website/static/index.html`
|
||||
1. Customize the `<title>` of `website/static/index.html`
|
||||
1. Delete the dynamic landing page `website/pages/en/index.js`
|
||||
|
||||
> Now, when Docusaurus generates or builds your site, it will copy the file from `static/index.html` and place it in the site's main directory. The static file is served when a visitor arrives on your page. When the page loads it will redirect the visitor to `/blog`.
|
||||
|
||||
You can use this template:
|
||||
|
||||
```html
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en-US">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta http-equiv="refresh" content="0; url=blog/">
|
||||
<script type="text/javascript">
|
||||
window.location.href = 'blog/';
|
||||
</script>
|
||||
<title>Title of Your Blog</title>
|
||||
</head>
|
||||
<body>
|
||||
If you are not redirected automatically, follow this <a href="blog/">link</a>.
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
{
|
||||
"version-1.3.0-docs": {
|
||||
"Getting Started": [
|
||||
"version-1.3.0-installation",
|
||||
"version-1.3.0-site-preparation",
|
||||
"version-1.3.0-site-creation",
|
||||
"version-1.3.0-publishing"
|
||||
],
|
||||
"Guides": [
|
||||
"version-1.3.0-adding-blog",
|
||||
"version-1.3.0-custom-pages",
|
||||
"version-1.3.0-search",
|
||||
"version-1.3.0-navigation",
|
||||
"version-1.3.0-translation",
|
||||
"version-1.3.0-versioning"
|
||||
],
|
||||
"API": [
|
||||
"version-1.3.0-commands",
|
||||
"version-1.3.0-doc-markdown",
|
||||
"version-1.3.0-api-pages",
|
||||
"version-1.3.0-site-config"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
[
|
||||
"1.3.0",
|
||||
"1.2.1",
|
||||
"1.2.0",
|
||||
"1.1.5",
|
||||
|
|
|
|||
Loading…
Reference in New Issue