diff --git a/website/docs/blog.md b/website/docs/blog.md index 2f9c6c849b..9e61e3470d 100644 --- a/website/docs/blog.md +++ b/website/docs/blog.md @@ -3,7 +3,102 @@ id: blog title: Blog --- -_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ +## Initial setup + +To setup your site's blog, start by creating a `blog` directory. + +Then, add a navbar link to your blog within `docusaurus.config.js`: + +```js +links: [ + ... + {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right' + ... +] +``` + +## 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 `my-website/blog/2019-09-05-hello-docusaurus-v2.md`: + +```yml +--- +title: Welcome Docusaurus v2 +author: Dattatreya Tripathy +authorTitle: Contributor of Docusaurus 2 +authorURL: https://github.com/dt97 +authorTwitter: CuriousDT +tags: [hello, docusaurus-v2] +--- + +Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**] +(https://v2.docusaurus.io/). + + + +This is my first post on Docusaurus 2. + +A whole bunch of exploration to follow. +``` + +## Header options + +The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options. + +- `author` - The author name to be displayed. +- `authorURL` - The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook account URL, etc. +- `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. +- `tags` - A list of strings to tag to your post. + +## Summary truncation + +Use the `` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `` will be part of the summary. For example: + +```yml +--- +title: Truncation Example +--- + +All this will be part of the blog post summary. + +Even this. + + + +But anything from here on down will not be. + +Not this. + +Or this. +``` + +## Advanced topics + +### Blog-only mode + +You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. Make sure there's no `index.js` page in `src/pages` or else there could be a conflict of paths! + +```diff +// docusaurus.config.js +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + blog: { + path: './blog', ++ routeBasePath: '/', + }, + }, + ], + ], +}; +``` +