diff --git a/blog/2017/09/25/testing-rss.html b/blog/2017/09/25/testing-rss.html index bac138b7ba..bd8319146e 100644 --- a/blog/2017/09/25/testing-rss.html +++ b/blog/2017/09/25/testing-rss.html @@ -1,4 +1,4 @@ -Adding RSS Support - RSS Truncation Test · Docusaurus

Docusaurus

Adding RSS Support

September 26, 2017

Eric Nakagawa

This is a test post.

A whole bunch of other information.

Recent Posts

New Version 1.0.0

October 24, 2017

Eric Nakagawa

This blog post will test file name parsing issues when periods are present.

Recent Posts
Edit

Pages and Styles

Docusaurus provides support for writing pages as React components inside the website/pages folder which will share the same header, footer, and styles as the rest of the site.

+
Edit

Pages and Styles

Docusaurus provides support for writing pages as React components inside the website/pages folder which will share the same header, footer, and styles as the rest of the site.

Urls for Pages

Any .js files in website/pages will be rendered to static html using the path of the file after "pages". Files in website/pages/en will also get copied out into pages and will OVERRIDE any files of the same name in pages. For example, the page for the website/pages/en/help.js file will be found at the url ${baseUrl}en/help.js as well as the url ${baseUrl}help.js, where ${baseUrl} is the baseUrl field set in your siteConfig.js file.

Page Require Paths

@@ -87,7 +87,7 @@ Background choices: dark, highlight, lightYou can provide your own custom styles by adding them anywhere in the website/static folder. Any .css files you provide in the static folder will get concatenated to the end of Docusaurus's provided styles, allowing you to add to or override Docusaurus default styles as you wish.

An easy way to figure out what classes you wish to override or add to is to start your server locally and use your browser's inspect element tool.

← CLI CommandssiteConfig.js →
Edit

Adding a Blog

Initial Setup

+
Edit

Adding a Blog

Initial Setup

To setup your site's blog, start by creating a blog folder within your repo's website directory.

Then, add a header link to your blog within siteConfig.js:

headerLinks: [
@@ -55,7 +55,7 @@
 
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  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 chacters are used.
← Navigation and SidebarsTranslations & Localization →
Edit

CLI Commands

Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. These scripts can be invoked with the run command when using Yarn or npm. Some common commands are:

+
Edit

CLI Commands

Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. These scripts can be invoked with the run command when using Yarn or npm. Some common commands are:

  • yarn run start: build and serve the website from a local server
  • yarn run examples: create example configuration files
    • @@ -54,7 +54,7 @@
    • GIT_USER: The git user to be associated with the deploy commit.
    • CIRCLE_BRANCH: The git branch associated with the commit that triggered the CI run.
      • -
    • CIRCLE_PROJECT_USERNAME: The GitHub username or organization name that hosts the git repo, e.g. "FacebookExperimental".
      • +
    • CIRCLE_PROJECT_USERNAME: The GitHub username or organization name that hosts the git repo, e.g. "facebook".
    • CIRCLE_PROJECT_REPONAME: The name of the git repo, e.g. "Docusaurus".
    • CI_PULL_REQUEST: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
    @@ -78,7 +78,7 @@

    Alias: write-translations

    Writes the English for any strings that need to be translated into an website/i18n/en.json file. The script will go through every file in website/pages/en and through the siteConfig.js file and other config files to fetch English strings that will then be translated on Crowdin. See the Translation guide to learn more.

← VersioningPages and Styles →
Edit

Custom Pages

You can add pages to your site that are not part of the standard docs or blog markdown files. You can do this by adding .js files to the website/pages directory. These files are React components and the render() is called to create them, backed by CSS classes, etc.

+
Edit

Custom Pages

You can add pages to your site that are not part of the standard docs or blog markdown files. You can do this by adding .js files to the website/pages directory. These files are React components and the render() is called to create them, backed by CSS classes, etc.

Customizing Your Home Page

The easiest way to get started customizing your home page is to use the example site that was created when you ran the Docusaurus initialization script.

You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

@@ -47,7 +47,7 @@ module.exports = Footer;
← Publishing your siteNavigation and Sidebars →
Edit

Markdown Features

Markdown Headers

+
Edit

Markdown Features

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 it's file name (without the extension).

@@ -105,7 +105,7 @@ ReactDOM.render( }
← siteConfig.js
Edit

Installation

Docusaurus was designed from the ground up to be easily installed and used to get your website up an running quickly. To install Docusaurus, we have created an easy script that will get all of the infrastructure setup for you:

+
Edit

Installation

Docusaurus was designed from the ground up to be easily installed and used to get your website up an running quickly. To install Docusaurus, we have created an easy script that will get all of the infrastructure setup for you:

  1. Go into the root of your GitHub repo directory where you will be creating the docs.
  2. yarn global add docusaurus-init or npm install --global docusaurus-init
    3. @@ -35,7 +35,7 @@

    If you do not want to install the init script globally, you can install it locally and then run it from the node_modules directory that is created via ./node_modules/.bin/docusaurus-init. You may want to remove the created package.json file and node_modules directory after you run the script.

Site Preparation →
Edit

Navigation and Sidebars

How Documents are Linked

+
Edit

Navigation and Sidebars

How Documents are Linked

New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

For example, creating an empty file such as "docs/getting-started.md" will enable the new page URL as /docs/getting-started.html.

Suppose you add this to your document:

@@ -78,7 +78,7 @@

Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

headerLinks: [
   ...
-  { href: 'https://github.com/facebookexperimental/Docusaurus', label: 'GitHub' },
+  { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
   ...
 ],
@@ -105,7 +105,7 @@ ],
← Custom PagesAdding a Blog →
Edit

Publishing your site

You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

+
Edit

Publishing your site

You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

Building Static HTML Pages

To create a static build of your website, run the following script from the website directory:

yarn run build # or `npm run build`
@@ -24,8 +24,8 @@
 
Most of the work to publish to GitHub pages is done for you automatically through the publish-gh-pages script. You just need to determine the values for a few parameters required by the script.

 
Two of the required parameters are set in the siteConfig.js:

 
    
-
  • organizationName: The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the "facebookexperimental" GitHub organization.
    • 
-
  • projectName: The name of the GitHub repository for your project. For example, Docusaurus is hosted at https://github.com/facebookexperimental/docusaurus, so our project name in this case would be "docusaurus".
    • 
+
  • organizationName: The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the "facebook" GitHub organization.
    • 
+
  • projectName: The name of the GitHub repository for your project. For example, Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus".
    • 
 

 

 
While we recommend setting the above in siteConfig.js, you can also use environment variables ORGANIZATION_NAME and PROJECT_NAME.

@@ -50,7 +50,7 @@
 

 
The specified GIT_USER must have push access to the repository specified in the combination of organizationName and projectName.

 

-
You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of https://organizationName.github.io/projectName, or a custom domain if you have set that up. For example, Docusaurus' own GitHub Pages URL is https://docusaurus.io (it can also be accessed via https://facebookexperimental.github.io/docusaurus), because it is served from the gh-pages branch of the https://github.com/facebookexperimental/docusaurus GitHub repo. We highly encourage reading through the GitHub Pages documentation to learn more about how this hosting solution works.

+
You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of https://organizationName.github.io/projectName, or a custom domain if you have set that up. For example, Docusaurus' own GitHub Pages URL is https://docusaurus.io (it can also be accessed via https://facebook.github.io/docusaurus), because it is served from the gh-pages branch of the https://github.com/facebook/docusaurus GitHub repo. We highly encourage reading through the GitHub Pages documentation to learn more about how this hosting solution works.

 
You can run the command above any time you update the docs and wish to deploy the changes to your site. Running the script manually may be fine for sites where the documentation rarely changes and it is not too much of an inconvenience to remember to manually deploy changes.

 
However, you can automate the publishing process with continuous integration (CI).

 
Automating Deployments Using Continuous Integration

@@ -97,7 +97,7 @@ deployment:
 
If you would rather use a deploy key instead of a personal access token, you can by starting with the Circle CI instructions for adding a read/write deploy key.
← Creating your siteCustom Pages →
Edit

Enabling Search

Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

+
Edit

Enabling Search

Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

Enabling the Search Bar

Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

const siteConfig = {
@@ -48,7 +48,7 @@
 
To disable the search bar, comment out (recommended) or delete the algolia section in the siteConfig.js file.

 
Also, if you have customized the location of the search bar in headerLinks, set search: false.
← Translations & LocalizationVersioning →
Edit

siteConfig.js

A large part of site configuration is done by editing the siteConfig.js file.

+
Edit

siteConfig.js

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 someon. 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.

@@ -87,7 +87,7 @@ // url: "https://www.example.com", baseUrl: "/test-site/", // baseUrl: "/", - organizationName: "facebookexperimental", + organizationName: "facebook", projectName: "docusaurus", noIndex: false, headerLinks: [ @@ -135,7 +135,7 @@ module.exports = siteConfig;
← Pages and StylesMarkdown Features →
Edit

Creating your site

Docusaurus was created to hopefully make it super simple for you to create a site and documentation for your open source project.

+
Edit

Creating your site

Docusaurus was created to hopefully make it super simple for you to create a site and documentation for your open source project.

After installation and preparation, much of the work to create a basic site for your docs is already complete.

Site Structure

Your site structure looks like the following:

@@ -55,7 +55,7 @@ yarn run start # # navigate to http://localhost:3000
← Site PreparationPublishing your site →
Edit

Site Preparation

After installing Docusaurus, you now have a skeleton to work from for your specific website. With a few changes, you can verify that Docusaurus was installed correctly by running the site locally.

+
Edit

Site Preparation

After installing Docusaurus, you now have a skeleton to work from for your specific website. With a few changes, you can verify that Docusaurus was installed correctly by running the site locally.

Directory Structure

As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

root-of-repo
@@ -49,7 +49,7 @@
← InstallationCreating your site →
Edit

Translations & Localization

Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

+
Edit

Translations & Localization

Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

Docusaurus Translation Configurations

To generate example files for translations with Docusuaurus, run the examples script with the command line argument translations:

npm run examples translations
@@ -160,7 +160,7 @@ const translate = require("../../server/translate.js").translate;
 
Ensure in your Crowdin settings, in the Translations section, that "Duplicate Strings" are set to "Hide - all duplicates will share the same translation". This setting will ensure that identical strings between versions share a single translation.
← Adding a BlogEnabling Search →
Edit

Versioning

You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

+
Edit

Versioning

You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

How to Create New Versions

Run the following script to generate a starter versions page listing all the site versions:

yarn examples translations
@@ -52,7 +52,7 @@
 
Versioning and Translations

 
If you wish to use versioning and translations features, the crowdin.yaml file should be set up to upload and download versioned documents to and from Crowdin for translation. Translated, versioned files will go into the folder translated_docs/${language}/version-${version}/. For more information, check out the translations guide.
← Enabling SearchCLI Commands →