Publish Content with Docusaurus

easyDITA enables you to deliver content from the content library to a Docusaurus-built site hosted on Netlify or to generate a static Docusaurus site that you can preview locally and deploy on your own.

Netlify is an easy to use hosting service. For more information, see https://www.netlify.com/.

To learn how Docusaurus renders DITA maps, refer to Docusaurus Map Reference.
  1. In the content library, hover over a map, click the Output icon, and click Publish.
  2. From the list on the left, select a Docusaurus publishing scenario.
    The publishing scenarios are configured by your easyDITA administrator. For more information, see Docusaurus Publishing Scenarios Management.
  3. Optional: In the Enter Description field, enter a meaningful description.
    Once you publish the document, this description appears in the list of finished publishing jobs.
  4. To include Netlify deployment as part of the publish:
    Note: Depending on the scenario configuration, the following options may not be available.
    1. Select the Deploy to Netlify check box.
    2. From the Available sites drop-down menu, select the Netlify site that you want to deploy the content to.
      Important: If you don't select any item from the drop-down menu, the content will be deployed to the previously deployed site or in the event of lack of sites, a new site will be created.

      You can select the Show sites for other maps check box to show the Netlify sites that the map and other maps have already been deployed to.

  5. Set the publishing parameters.
    The publishing scenario can include the following parameters.
    Template
    Enables you to select output style.
    Ditaval (or args.filter)
    Enables you to select a DITAVAL file for conditional publishing.
    Locales
    Enables you to select a locale when publishing localized content.
    Webhooks
    Enables you to send webhooks on successful publish or any publish.
  6. Click Publish.
    The resource publishes. It may take a moment to complete.
Figure 1. Publish Window

In the Key Assets Section, the following links are provided:

full_project.zip
Useful if you want to develop your own Docusaurus template.
build.zip
Useful if you want to preview the Docusaurus static site locally or deploy the site on your own.
netlify.app
Useful if you deployed the Docusaurus static site to Netlify and you want to preview it.
Warning: If you change the site name on Netlify, the link to the site in the Publish Window will not update. This will lead to sites in affected publish records showcasing an error message rather than your Netlify site.

If you deployed content to Netlify as part of the publish:

  • For a map that was not deployed to Netlify yet, a new site is created.
  • For a map that was already deployed to Netlify, the site is updated.

Locally Preview a Docusaurus Static Site

You can host the Docusaurus output on a local web server to preview it.

  1. Download the build.zip key asset.
  2. Unzip the downloaded archive.
  3. Navigate to the unzipped folder and unzip the build.zip file.
  4. In the terminal, navigate to the unzipped build folder by entering cd publish_filepath
    Where, publish_filepath is the path to the build folder.
    Enter:
    • cd C:\users\your_username\Downloads\publish_name\build (Windows)
    • cd /Users/your_username/Downloads/publish_name/build (macOS)
    Where:
    • your_username is the name of the account that you are currently logged on your workstation
    • publish_name is the name of the folder that contains the published static site
  5. Start a local web server by entering npx serve
       │   Serving!                                       │
       │                                                  │
       │   - Local:                                       │
       │                   http://localhost:5000                │
       │                                                  │
       │   - On Your Network:  http://192.168.56.1:5000   │
       │                                                  │
       │   Copied local address to clipboard!             │
  6. In a web browser, go to the Local address.
To stop the local web server, in the terminal, press Ctrl > C.

Manually Deploy a Docusaurus Site

You can manually deploy a static site to Netlify or a similar static site hosting provider.

Publish a static site by using a Docusaurus scenario. See Publish Content with Docusaurus.
This procedure assumes that your hosting provider is Netlify.
  1. Download the build.zip key asset.
  2. Unzip the downloaded archive.
  3. In your web browser, go to https://app.netlify.com/.
  4. On Netlify, in the designated area in the Sites tab, drag and drop the build folder from the unzipped archive.

    Depending on the size of your static site, it can take a few minutes for Netlify to process the files and build the site.

Once the site built, you are able to see it as well as make any administrative changes you need. For more information, see https://docs.netlify.com/.