mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-02 02:42:41 +02:00
Documents Blog Only Mode and Netlify Hosting (#595)
* Documentation, newest: Add steps for hosting on Netlify * Documents how to run a blog-only site
This commit is contained in:
Eric Nakagawa
Joel Marcey
parent
ec13640097
commit
4e575e9234
2 changed files with 70 additions and 15 deletions
|
|
@ -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/<projectName>` (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.
|
||||
|
|
|
|||
|
|
@ -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 `<!--truncate
|
|||
## 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 folder. 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:
|
||||
|
||||
```<!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>
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue