fugashu / imx-docs Goto Github PK

Immutable X's documentation portal, built with Docusaurus.
Explore the docs »

• Introduction
  • Tech Stack
• Running Locally
  • Requirements
  • Installation
• Writing Documentation
  • Add or edit page
  • Add a new Sidebar Section
  • Add a code block
  • Add a table
  • Add an admonition
• Document Instance Versioning
• Hosted SDK API References
  • Linking to Hosted SDK API References
• Contributing
• Community Support
• License

The Immutable X documentation website is built using Docusaurus. Docusaurus is a static-site generator built with React and MDX. It builds a single-page application (SPA) that's SEO friendly. But you don't need to learn React to be able to write documentation or contribute to it! All docs are written in Markdown.

Internal Immutable X Developers: Please read over the SDK Documentation Guide on Confluence too.

• Docusaurus
• React
• MDX

• node
• yarn or npm

1. Clone the repo

git clone https://github.com/immutable/imx-docs/

2. Install dependencies

yarn install

3. Run the app

yarn run start

Read the Contributors Guide for more details

Adding a new page is simple! Identify the section under which your new page goes inside the docs folder, and then create a markdown file in that folder. For example, if you want to add a new page to the Link SDK guide, you'd create a new page under docs/guides/link-sdk. Ensure that the new page has a section at the top of the page like below, where you can specify the name of the article, the slug by which you can navigate to it, an excerpt and the page's position in the sidebar.

---
title: 'Link.buy'
slug: '/link-buy2'
excerpt: "Link can now be used to kick off buy flows containing multiple order ID's"
sidebar_position: 4
---

Refer to the Docusaurus Documentation on creating a page

Editing is even easier:

1. Open up the page you want to edit on your browser
2. Scroll to the bottom of the page
3. Click on Edit this page, and it'll take you to the file that you need to edit on GitHub.
4. Apply your edits, and send a pull request (PR)

If you want to add a new top level sidebar section:

1. Create a new folder under docs.
2. Create a file named _category_.json inside the newly created folder

{
    "label": "New section label",
    "position": 3
}

3. Create a file called index.md which will serve as the default page that renders when you navigate to the newly created section.
4. Add more pages to the section using the guide above.

Refer to the Docusaurus Documentation on Sidebars

The Docusaurus Documentation on Code Blocks is excellent!

We use mdx to enable adding HTML based tables to our docs. In order to enable mdx on a page, ensure that it's extension is .mdx. Now, that page can render any react component or valid HTML. See an example of a table here

Read more about using MDX and React in Docusaurus

Admonitions allow us to make our docs prettier and provide our users with tips, useful information, and cautions.

You can add an admonition using the following format:

:::note

Some **content** with _markdown_ `syntax`. Check [this `api`](#).

:::

Read more about using Admonitions in Docusaurus

Instructions for versioning a document instance with the Docusaurus CLI tool.

NOTE 1: Use the docusaurus CLI tool described here for versioning document instances. Attempting to copy/paste version folders may not work as expected.

NOTE 2: If the document instance only has 1 version of docs, do not version the document instance by running the CLI command below.

Each SDK has been configured as a docusaurus document instance. Each document instance id, which can be found in the docusaurus.config.js file.

// example docusaurus.config.js

plugins: [
  ...,
  [
    '@docusaurus/plugin-content-docs',
    {
      path: 'docs/sdk-docs/core-sdk-ts/',     // path to the markdown files
      routeBasePath: '/sdk-docs/core-sdk-ts', // URL path to rewrite in the browser
      id: 'sdks-core-sdk-ts',                 // doc instance id
      sidebarPath: require.resolve('./sidebars/sidebars-core-sdk-ts.js'),
      ...pageOptions
    },
  ],
  ...
]

Once you have the document instance id, the document instances can be versioned using the docusaurus CLI:

# versioning a specific doc instance
yarn run docusaurus docs:version:<doc_instance_id> <version>

This will copy the existing set of docs into a <doc_instance_id>_versioned_docs/version-<version> folder in the root of the project folder (this appears to be unconfigurable).

A few things to note once a document set has been versioned:

• The SDK files docs/main/sdk-docs/<your_sdk> are now treated as the next version set of docs. Updating those docs will not update the docs on the published site. These docs will be used when running the version command (above) to generate a new version of the docs. So once a document instance has been versioned, treat the docs in docs/main/sdk-docs/<your_sdk> as work in progress version of your doc instance.
• To update the latest/current (or previous) version docs, you will need to update the files in the appropriate <doc_instance_id>_versioned_docs/version-<version> folder.
• A version switcher button will appear next to the SDK switcher button of the newly versioned SDK docs. Example of the version switcher (in the right-hand sidebar).

Check out the docusaurus docs on versioning for more info about how document instance versioning works.

SDK API reference documentation can be hosted as static assets.

Put the generated docs in the api-docs/sdk-references folder in the appropriate SDK folder. Rename the API reference folder to be the version number, replacing . with - in the folder name.

api-docs/
  sdk-references/
    <core-sdk-lang>
      <x-x-x>
        index.html # docs entry point

The SDK API references should be available at <docsBaseUrl>/sdk-references/<core-sdk-lang>/<x-x-x>/

If you want a sidebar link to the hosted API reference, add a link type sidebar item to the respective SDK sidebar config:

  // example link type config object
  {
    type: 'link',
    label: 'Reference',
    href: `${url}/sdk-references/<core-sdk-lang>/<x-x-x>/`,
  },

Check the Core SDK TypeScript sidebar config for an example.

We're excited to enable you to contribute! Before you start contributing, please read the Contributors Guide and the code of conduct.

Need help with something that's not covered in the docs? Ask questions on the Immutable X Discord server or the Immutable Forum.

Distributed under the Apache License, Version 2.0. See LICENSE for more information.