Technology, Tutorials, Announcements, News, Tool Support, for User, for Developer

Announcing Klaytn Docs 2.0: Streamlined, Searchable, and Community-Powered

#Blockchain #Klaytn #Technology

Upgrade your Klaytn learning journey with a powerful new docs platform!

We’re thrilled to announce the launch of Klaytn Docs 2.0, a major upgrade to our official documentation platform! This exciting release brings significant improvements in search capability, discoverability, and customizability, making it easier than ever to find the information you need to build and interact with the Klaytn blockchain.

Why the Move to Docusaurus?

Our docs site initially resided on Gitbook, which served us well during our early stages. However, as our community grew and documentation contributions flourished, we encountered limitations in search, versioning, in-context language switching, and customization. To provide a seamless experience for both users and contributors, we’ve migrated to Docusaurus, offering:

  • Multi-language support
    Effortlessly switch between languages on the same page.
  • Enhanced search
    Algolia-powered search makes finding information a breeze.
  • Extension flexibility
    Leverage a vast plugin ecosystem to tailor the site to the user’s needs.
  • Customizable layout
    Design a user-friendly and intuitive interface.

Content Restructured for Clarity and Ease of Navigation:

In addition to the platform migration, we also took this opportunity to restructure the table of contents (TOC) to make the content more discoverable.

  • Four pillars
    Organize your learning journey with “Learn,” “Build,” “Nodes,” and “References” categories for intuitive navigation.
  1. Learn – Foundational concepts for understanding Klaytn.
  2. Build – Technical tutorials and guides for building on Klaytn.
  3. Nodes – Documentation related specifically to operating Klaytn nodes.
  4. References – API and SDK references and detailed technical explanations.
  • Reduced complexity
    Minimized cognitive load by streamlining subcategories and presenting information in manageable chunks.
  • Discoverable content
    Regrouped content by thematic affinities for quicker access to relevant resources.

For Content Contributors

We value your contributions! Klaytn Docs 2.0 remains open-source, relying on your dedication. For a smooth transition to the new setup, here’s what you need to know:

Content

  • Markdown file location
    Find your previous content’s new location and map your contributions onto the revised structure along with updated content navigation. 
  • Image placement
    The image directory locations are centralized for consistency and ease of management.
    • Before: Images were scattered alongside content files by using relative paths.
    • After: Images are unified in /static/img/ directory by using absolute paths., organized by topics.
  • Github repositories
    • Before
      • Docs repos: klaytn-docs, klaytn-docs-vn, klaytn-docs-ko
      • Localization branch: klaytn-docs > l10n
    • After
      • Docs repos: klaytn-docs (klaytn-docs-vn and klaytn-docs-ko are no longer in use and archived.)
      • Localization branch: klaytn-docs > l10n_main
  • Contribution in Crowdin
    You can continue to contribute to Klaytn docs localization project as a translator.

Platform (Gitbook vs Docusaurus)

  • Project structure
    Understand how Docusaurus organizes directories and files compared to Gitbook.
  • Gitbook
klaytn-docs
├── docs # content files
│    ├── dapp
│    ├── getting-started
│    ├── klaytn2
│    ├── misc
│    ├── …
│    ├── SUMMARY.md # content navigation on the left
│    └── README.md # Landing page for Klaytn docs
├── …
└── README.md # “This website is built using Gitbook”
  • Docusaurus
klaytn-docs
├── docs  # English content files
│    ├── build
│    ├── learn
│    ├── misc
│    ├── nodes
│    └── references
├── i18n  # Localized content files
│    ├── ko # Korean
│    └── vi # Vietnamese
├── docusaurus.config.js # main configuration file
├── sidebars.js # content navigation on the left
├── package.json # required package information
├── …
└── README.md # “This website is built using Docusaurus”
  • Language management
    Identify how the two platforms differ in managing different languages.
    • Gitbook
      Requires separate repositories or projects for each language. (e.g. klaytn-docs, klaytn-docs-ko, klaytn-docs-vn)
    • Docusaurus
      Uses a single repository (i.e. klaytn-docs) with language folders, offering a unified approach.
  • Navigation file
    Learn about which file constructs the left navigation menu that outlines the structure and topics of the content.
    • Gitbook: SUMMARY.md
    • Docusaurus: sidebars.js
  • Use of README.md
    • Gitbook: Each category had a README.md serving as an entry point. (e.g. /deployment/service-chain/README.md)
    • Docusaurus: We’ve moved to using a markdown file named after the parent folder instead of using README.md. (e.g. /nodes/service-chain/service-chain.md)
  • Markdown syntax changes
    While the syntax remains largely the same with some differences around mdx syntax, here are some important highlights for contributors moving forward:
  1. First level heading
    Ensure a first-level heading is present on every page. While Gitbook lets you skip first-level headings as long as they’re defined in SUMMARY.md, Docusaurus needs them on every page for proper documentation.

▪️ Incorrect

Endpoint Node exposes JSON-RPC APIs. You can enable/disable APIs as follows. For the detailed API specification, please refer to the [JSON-RPC APIs](../../../dapp/json-rpc/README.md).


## Enabling APIs  <a id="enabling-apis"></a>

▪️ Correct

# JSON-RPC APIs


Endpoint Node exposes JSON-RPC APIs. You can enable/disable APIs as follows. For the detailed API specification, please refer to the [JSON-RPC APIs](../../references/json-rpc/json-rpc.md).


## Enabling APIs  <a id="enabling-apis"></a>

2. Section IDs
Avoid adding section IDs to first-level headings to prevent unintended appearances in the sidebar.

▪️ Incorrect

# System Requirements <a id="system-requirements"></a>


## H/W Specification <a id="h-w-specification"></a>

▪️ Correct

# System Requirements


## H/W Specification <a id="h-w-specification"></a>

3. Other syntax specifics
Some existing syntax is no longer supported.

a. Admonitions (NOTE, CAUTION, WARNING, TIPS)
: Use Docusaurus admonitions instead of Gitbook’s hints where applicable.

b. Line breaks in tables
: Use <br/> instead of <br> or </br> when you put a line break in a table.

▪️ Incorrect

| Type | Description |
| --- | --- |
| QUANTITY | The integer of the network identifier.<br>- `"1001"`: Klaytn Baobab testnet.<br>- `"8217"`: Klaytn Cypress mainnet.|

▪️ Correct

| Type | Description |
| --- | --- |
| QUANTITY | The integer of the network identifier.<br/>- `"1001"`: Klaytn Baobab testnet.<br/>- `"8217"`: Klaytn Cypress mainnet.|

c. Bad usage of { or <
: Given the Klaytn docs 2.0 is built using Docusaurus v3 and MDX v3, you may encounter some compilation issues during the build process if you use { or < incorrectly in your Markdown files because MDX v3 compiles them more strictly. The { character is used for opening JavaScript expressions whereas the < character is used for opening JSX tags. If MDX finds the expression inside { } or <> invalid, it will fail.

One of the options to fix this kind of issue is to escape it by prepending escaping backslash (\).

  • Incorrect
| \[\]{\*big.Int, \*big.Int, \*big.Int\} \(Go\) |
  • Correct 
| \[\]\{\*big.Int, \*big.Int, \*big.Int\} \(Go\) |
  • Incorrect
| Array<String\|Object\>\|Object|
  • Correct
| Array\<String\|Object\>\|Object|

We believe Klaytn Docs 2.0 is a significant step forward in making Klaytn more accessible and user-friendly for everyone. We’re excited to see how it empowers our community to build, innovate, and explore the possibilities of Klaytn blockchain.

Join us on this exciting journey towards smoother learning and empowered community participation! 

Get started with Klaytn Docs 2.0 today!

*FAQ

Q: Where did the old docs site go?
A: The previous docs content hosted on GitBook is still available and archived at the following URLs:

– English: https://archive-docs.klaytn.foundation/
– Korean: https://archive-ko.docs.klaytn.foundation/
– Vietnamese: https://archive-vn.docs.klaytn.foundation/ 

We have also redirected all the old URLs to the new site, so existing links should not break.


Q: Where can I find content that was previously located in a different directory?
A: We’ve created a detailed mapping table that shows where old content has been moved in the Docusaurus structure. You can access this table here.

Q: How do I handle images and media files?
A: Images should now be placed in the centralized /static folders. Specify the path like /static/img/build/my-image.png in Markdown. Other media can be placed there as well. For more information, see this table.

Q: Will there be any downtime during the transition to Docusaurus?
A: We aim to make the transition as seamless as possible. However, if there is any expected downtime, we will communicate it ahead of time through our official channels.

RELATED ARTICLE

Back to list