Publish v1.0.13 (#589)

CHANGELOG.md

@@ -6,6 +6,32 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [1.0.13] - 2018-04-20
+
+This is primarily a bug fix release.
+
+Thank you to the following contributors who helped with this release:
+
+- @vjeux
+- @huang-x-h
+
+### Breaking changes
+
+N/A
+
+### Added
+
+- Support for [custom highlight theme URL](https://github.com/facebook/Docusaurus/commit/aa32ff4a558269a2ac02f265489804ab83cc0145) via the `themeURL` site config option.
+
+### Fixed/Changed
+
+- [Do not warn](https://github.com/facebook/Docusaurus/commit/c400636fb6a790ac39cb731ed3fe2f0cd22313eb) when using `layout` in the docs metadata header.
+- [Restore](https://github.com/facebook/Docusaurus/commit/1d4e334a86cabb9581a3ba5305a2019a7bbb540d) the ability to use the --port command line argument
+
+### Removed
+
+N/A
+
 ## [1.0.12] - 2018-04-18
 
 This is a general release with additions and documentation updates. We would also like to welcome [React Native Elements](https://react-native-training.github.io/react-native-elements/) as a user of Docusaurus.
@@ -269,7 +295,8 @@ N/A
   - Blog
   - Documentation
 
-[Unreleased]: https://github.com/facebook/Docusaurus/compare/v1.0.12...HEAD
+[Unreleased]: https://github.com/facebook/Docusaurus/compare/v1.0.13...HEAD
+[1.0.13]: https://github.com/facebook/Docusaurus/compare/v1.0.12...v1.0.13
 [1.0.12]: https://github.com/facebook/Docusaurus/compare/v1.0.11...v1.0.12
 [1.0.11]: https://github.com/facebook/Docusaurus/compare/v1.0.10...v1.0.11
 [1.0.10]: https://github.com/facebook/Docusaurus/compare/v1.0.9...v1.0.10

package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "license": "MIT",
   "keywords": [
     "documentation",

website/versioned_docs/version-1.0.13/api-site-config.md

@@ -0,0 +1,234 @@
+---
+id: version-1.0.13-site-config
+title: siteConfig.js
+original_id: site-config
+---
+
+A large part of site configuration is done by editing the `siteConfig.js` file.
+
+## User Showcase
+
+The `users` array is used to store objects for each project/user that you want to show on your site. Currently this field is used by example the `pages/en/index.js` and `pages/en/users.js` files provided. Each user object should have `caption`, `image`, `infoLink`, and `pinned` fields. The `caption` is the text showed when someone hovers over the `image` of that user, and the `infoLink` is where clicking the image will bring someone. The `pinned` field determines whether or not it shows up on the `index` page.
+
+Currently this `users` array is used only by the `index.js` and `users.js` example files. If you do not wish to have a users page or show users on the `index` page, you may remove this section.
+
+## siteConfig Fields
+
+The `siteConfig` object contains the bulk of the configuration settings for your website.
+
+### Mandatory Fields
+
+`baseUrl` - baseUrl for your site.
+
+`colors` - Color configurations for the site.
+
+  - `primaryColor` is the color used the header navigation bar and sidebars.
+  - `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
+  - Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color.
+
+`copyright` - The copyright string at footer of site and within feed
+
+`favicon` - url for site favicon.
+
+`headerIcon` - url for icon used in header navigation bar.
+
+`headerLinks` - Links that will be used in the header navigation bar. The `label` field of each object will be the link text and will also be translated for each language.
+
+Example Usage:
+```js
+headerLinks: [
+  // Links to document with id doc1 for current language/version
+  { doc: "doc1", label: "Getting Started" },
+  // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
+  { page: "help", label: "Help" },
+  // Links to href destination
+  { href: "https://github.com/", label: "GitHub" },
+  // Links to blog generated by Docusaurus (${baseUrl}blog)
+  { blog: true, label: "Blog" },
+  // Determines search bar position among links
+  { search: true },
+  // Determines language drop down position among links
+  { languages: true }
+],
+```
+
+`noIndex` - Boolean. If true, Docusaurus will politely ask crawlers and search engines to avoid indexing your site. This is done with a header tag and so only applies to docs and pages. Will not attempt to hide static resources. This is a best effort request. Malicious crawlers can and will still index your site.
+
+`organizationName` - GitHub username of the organization or user hosting this project. This is used by the publishing script to determine where your GitHub pages website will be hosted.
+
+`projectName` - Project name. This must match your GitHub repo project name (case sensitive).
+
+`tagline` - Tagline for your website.
+
+`title` - Title for your website.
+
+`url` - url for your site.
+
+### Optional Fields
+
+`algolia` - Information for Algolia search integration. If this field is excluded, the search bar will not appear in the header. You must specify two values for this field, and one (`appId`) is optional.
+
+- `apiKey` - the Algolia provided API key for your search.
+- `indexName` - the Algolia provided index name for your search (usually this is the project name)
+- `appId` - Algolia provides a default scraper for your docs. If you provide your own, you will probably get this id from them.
+
+`blogSidebarCount` - Control the number of blog posts that show up in the sidebar. See the [adding a blog docs](guides-blog.md#changing-how-many-blog-posts-show-on-sidebar) for more information.
+
+`cname` - The CNAME for your website. It will go into a `CNAME` file when your site it built.
+
+`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"
+```
+`disableHeaderTitle` - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to `true`.
+
+`disableTitleTagline` - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as `Title • Tagline`. Set to `true` to make page titles just `Title`.
+
+`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.
+
+`facebookAppId` - If you want Facebook Like/Share buttons at the bottom of your blog posts, provide a [Facebook application id](https://www.facebook.com/help/audiencenetwork/804209223039296), and the buttons will show up on all blog posts.
+
+`facebookPixelId` - [Facebook Pixel](https://www.facebook.com/business/a/facebook-pixel) ID to track page views.
+
+`fonts` - Font-family css configuration for the site. If a font family is specified in `siteConfig.js` as `$myFont`, then adding a `myFont` key to an array in `fonts` will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.
+
+In the below example, we have two sets of font configurations, `myFont` and `myOtherFont`. `Times New Roman` is the preferred font in `myFont`. `-apple-system` is the preferred in `myOtherFont`.
+
+```
+fonts: {
+  myFont: [
+    "Times New Roman",
+    "Serif"
+  ],
+  myOtherFont: [
+    "-apple-system",
+    "system-ui"
+  ]
+},
+```
+
+The above fonts would be represented in your CSS file(s) as variables `$myFont` and `$myOtherFont`.
+
+```
+h1 {
+  font-family: $myFont;
+}
+```
+
+`footerIcon` - URL for a footer icon. Currently used in the `core/Footer.js` file provided as an example, but it can be removed from that file.
+
+`gaTrackingId` - Google Analytics tracking ID to track page views.
+
+`highlight` - [Syntax highlighting](api-doc-markdown.md) options:
+
+ - `theme` is the name of the theme used by Highlight.js when highlighting code. You can find the [list of supported themes here](https://github.com/isagalaev/highlight.js/tree/master/src/styles).
+ - `version` specifies a particular version of Highlight.js to be used.
+ - `hljs` provides an escape valve by passing an instance of Highlight.js to the function specified here, allowing additional languages to be registered for syntax highlighting.
+ - `defaultLang` defines a default language. It will be used if one is not specified at the top of the code block. You can find the [list of supported languages here](https://github.com/isagalaev/highlight.js/tree/master/src/languages).
+ - `themeUrl` is the custom URL of CSS theme file that you want to use with Highlight.js. If this is provided, the `theme` and `version` fields will be ignored.
+
+`markdownPlugins` - An array of plugins to be loaded by Remarkable, the markdown parser and renderer used by Docusaurus. The plugin will receive a reference to the Remarkable instance, allowing custom parsing and rendering rules to be defined.
+
+`ogImage` - Local path to an Open Graph image (e.g., `img/myImage.png`). This image will show up when your site is shared on Facebook and other websites/apps where the Open Graph protocol is supported.
+
+`onPageNav` - If you want a visible navigation option for representing topics on the current page. Currently, there is one accepted value for this option:
+
+- `separate` - The secondary navigation is a separate pane defaulting on the right side of a document. See http://docusaurus.io/docs/en/translation.html for an example.
+
+`scripts` - Array of JavaScript sources to load. The script tag will be inserted in the HTML head.
+
+`separateCss` - Folders inside which any `css` files will not be processed and concatenated to Docusaurus' styles. This is to support static `html` pages that may be separate from Docusaurus with completely separate styles.
+
+`stylesheets` - Array of CSS sources to load. The link tag will be inserted in the HTML head.
+
+`translationRecruitingLink` - URL for the `Help Translate` tab of language selection when languages besides English are enabled. This can be included you are using translations but does not have to be.
+
+`twitter` - Set this to `true` if you want a Twitter social button to appear at the bottom of your blog posts.
+
+`twitterImage` - Local path to your Twitter card image (e.g., `img/myImage.png`). This image will show up on the Twitter card when your site is shared on Twitter. 
+
+`useEnglishUrl` - If you do not have [translations](guides-translation.md) enabled (e.g., by having a `languages.js` file), but still want a link of the form `/docs/en/doc.html` (with the `en`), set this to `true`.
+
+`users` - The `users` array mentioned earlier.
+
+`wrapPagesHTML` - Boolean flag to indicate whether `html` files in `/pages` should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being `html` fragments instead of complete pages. It inserts the contents of your `html` file with no extra processing. Defaults to `false`.
+
+Users can also add their own custom fields if they wish to provide some data across different files.
+
+## Example siteConfig.js with many available fields
+
+```
+const users = [
+  {
+    caption: "User1",
+    image: "/test-site/img/docusaurus.svg",
+    infoLink: "https://www.example.com",
+    pinned: true
+  }
+];
+
+const siteConfig = {
+  title: "Docusaurus",
+  tagline: "Generate websites!",
+  url: "https://docusaurus.io",
+  baseUrl: "/",
+  // For github.io type URLS, you would combine the url and baseUrl like:
+  // url: "https://reasonml.github.io",
+  // baseUrl: "/reason-react/",
+  organizationName: "facebook",
+  projectName: "docusaurus",
+  noIndex: false,
+  // For no header links in the top nav bar -> headerLinks: [],
+  headerLinks: [
+    { doc: "doc1", label: "Docs" },
+    { page: "help", label: "Help" },
+    { search: true },
+    { blog: true }
+  ],
+  headerIcon: "img/docusaurus.svg",
+  favicon: "img/favicon.png",
+  colors: {
+    primaryColor: "#2E8555",
+    secondaryColor: "#205C3B"
+  },
+  editUrl: "https://github.com/facebook/docusaurus/edit/master/docs/",
+  // Users variable set above
+  users,
+  disableHeaderTitle: true,
+  disableTitleTagline: true,
+  separateCss: ["static/css/non-docusaurus", "static/assets/separate-css"],
+  footerIcon: "img/docusaurus.svg",
+  translationRecruitingLink:
+    "https://crowdin.com/project/docusaurus",
+  algolia: {
+    apiKey:
+      "0f9f28b9ab9efae89810921a351753b5",
+    indexName: "github"
+  },
+  gaTrackingId: "U-A2352",
+  highlight: {
+    theme: 'default'
+  },
+  markdownPlugins: [
+    function foo(md) {
+      md.renderer.rules.fence_custom.foo = function(tokens, idx, options, env, instance) {
+        return '<div class="foo">bar</div>';
+      }
+    }
+  ],
+  scripts: [ "https://docusaurus.io/slash.js" ],
+  stylesheets: [ "https://docusaurus.io/style.css" ],
+  facebookAppId: "1615782811974223",
+  facebookPixelId: "352490515235776",
+  twitter: "true",
+  twitterImage: "img/docusaurus.png",
+  ogImage: "img/docusaurus.png",
+};
+
+module.exports = siteConfig;
+```

website/versions.json

@@ -1,4 +1,5 @@
 [
+  "1.0.13",
   "1.0.12",
   "1.0.11"
 ]