From 4e575e9234f6fd7098e177adb9663e7681d1097b Mon Sep 17 00:00:00 2001 From: Eric Nakagawa Date: Mon, 23 Apr 2018 13:45:02 -0700 Subject: [PATCH] Documents `Blog Only` Mode and Netlify Hosting (#595) * Documentation, newest: Add steps for hosting on Netlify * Documents how to run a blog-only site --- docs/getting-started-publishing.md | 35 ++++++++++++++++----- docs/guides-blog.md | 50 +++++++++++++++++++++++++----- 2 files changed, 70 insertions(+), 15 deletions(-) diff --git a/docs/getting-started-publishing.md b/docs/getting-started-publishing.md index c233e29bd865..df0c10edb3b0 100644 --- a/docs/getting-started-publishing.md +++ b/docs/getting-started-publishing.md @@ -21,6 +21,11 @@ At this point, you can grab all of the files inside the `website/build` folder a > For example, both Apache and nginx serve content from `/var/www/html` by default. That said, choosing a web server or provider is outside the scope of Docusaurus. +### Hosting on a Service: + +* [Github Pages](#using-github-pages) +* [Netlify](#hosting-on-netlify) + ### Using GitHub Pages While choosing a web server or host is outside Docusaurus' scope, Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: [GitHub Pages](https://pages.github.com/). @@ -82,13 +87,13 @@ Continuous integration (CI) services are typically used to perform routine tasks If you haven't done so already, you can [setup CircleCI](https://circleci.com/signup/) for your open source project. Afterwards, in order to enable automatic deployment of your site and documentation via CircleCI, just configure Circle to run the `publish-gh-pages` script as part of the deployment step. You can follow the steps below to get that setup. -1. Ensure the GitHub account that will be set as the `GIT_USER` has `write` access to the repo that contains the documentation, by checking `Settings | Collaborators & teams` in the repo. -1. Log into GitHub as the `GIT_USER`. -1. Go to https://github.com/settings/tokens for the `GIT_USER` and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/), granting it full control of private repositories through the `repo` access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password. -1. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/ORG/REPO/edit#env-vars, where "ORG/REPO" should be replaced with your own GitHub org/repo. -1. Create a new environment variable named `GITHUB_TOKEN`, using your newly generated access token as the value. -1. Create a `.circleci` folder and create a `config.yml` under that folder. -1. Copy the text below into `.circleci/config.yml`. +1. Ensure the GitHub account that will be set as the `GIT_USER` has `write` access to the repo that contains the documentation, by checking `Settings | Collaborators & teams` in the repo. +1. Log into GitHub as the `GIT_USER`. +1. Go to https://github.com/settings/tokens for the `GIT_USER` and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/), granting it full control of private repositories through the `repo` access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password. +1. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/ORG/REPO/edit#env-vars, where "ORG/REPO" should be replaced with your own GitHub org/repo. +1. Create a new environment variable named `GITHUB_TOKEN`, using your newly generated access token as the value. +1. Create a `.circleci` folder and create a `config.yml` under that folder. +1. Copy the text below into `.circleci/config.yml`. ```yml # If you only one circle to run on direct commits to master, you can uncomment this out @@ -155,3 +160,19 @@ jobs: ``` Save this file as `config.yml` and place it in a `.circleci` folder inside your `website/assets` folder. + +### Hosting on Netlify + +Steps to configure your Docusaurus-powered site on Netlify. + +1. Select **New site from Git** +2. Connect to your preferred Git provider. +3. Select the branch to deploy. Default is `master` +4. Configure your build steps: + +* For your build command enter: `cd website; npm install; npm run build;` +* For publish directory: `build/` (use the projectName from your siteConfig) + +5. Click **Deploy site** + +You can also configure Netlify to rebuild on every commit to your repo, or only `master` branch commits. diff --git a/docs/guides-blog.md b/docs/guides-blog.md index 50c589591b24..430874d6d4d5 100644 --- a/docs/guides-blog.md +++ b/docs/guides-blog.md @@ -17,7 +17,6 @@ headerLinks: [ ] ``` - ## Adding Posts To publish in the blog, create a file within the blog folder with a formatted name of `YYYY-MM-DD-My-Blog-Post-Title.md`. The post date is extracted from the file name. @@ -35,17 +34,15 @@ 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. - +* `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 @@ -78,6 +75,7 @@ You can configure a specific amount of blog posts to show by adding a `blogSideb The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'. Example: + ``` blogSidebarCount: 'ALL' ``` @@ -91,3 +89,39 @@ A summary of the post's text is provided in the RSS feed up to the `