Documentation migration update

Community
,
1

Just a note that the documentation migration is still happening, and that the GitHub wiki should be considered just a staging ground for working on docs before ultimately publishing them on docs.teia.art.

This has been a multi-year effort so far to get to the point now, where we have Docusaurus instance setup which looks nice and is easy to maintain. There were several hurdles for getting through to where we are today:

  1. Understand the GitHub Wiki Feature

A GitHub wiki is a separate, hidden repo, associated with a GitHub project. While it presents an easy to use interface to update files in this repo, the feature is meant to create quick docs, “meta docs”, to describe how to use a repo, it’s not intended to be used as a standalone project wiki.

This was frustrating to users who came in later and wanted to contribute to the documentation in a traditional git flow way, where docs are updated, a Pull Request is created and approved, and then the change is accepted and merged to the main branch.

To address this, we created a two-way GitHub Action file sync so that when files were edited using the wiki interface, they would be copied to a folder in the main “teia-docs” repo:

  • //teia-docs/wiki

And conversely when someone edited the docs in the teia-docs/wiki folder using the normal Git workflow, once the PR was accepted the action would synchronize this change to the internal wiki repo.

This is still a useful tool for drafting documentation if desired, but the wiki should no longer be considered the source of truth or final stage of publication for Teia documentation.

  1. Understand the Docusaurus Navigation Menu

Now the wiki navigation and the Docusaurus navigation system needed to be reconciled. Docusaurus offers more features to manage navigation, like autogenerated navbar:

  • docusaurus io/docs/sidebar/autogenerated

Which makes it easier to maintain the navigation menu when adding new docs. The GitHub wiki navigation menu items and structure had to be adapted a bit to work well with Docusaurus.

  1. Setup the Docusaurus publishing action and update DNS

This has been completed now, so that documentation can be updated and new documentation pages can be added following the guide here:

We are in the clean-up phase now and there is an issue to organise updating links, this is being tracked in this issue:

My ETA for completing the migration clean-up phase is hand wave some time in 2026.

1 Like
2

Chatting in the Teia Discord documentation today, at least one person makes the case for keeping the docs in the UI.

I’m reviewing other docs, and noticed the Privacy Policy only seems to exist in the UI code.

I took a quick look at how docs are managed in the Teia UI, and they are mixed up in src/pages some of the code in that directory are pages, like the tab for creating swaps, and then some pages to contain documentation is managed here.

It’s not a pleasant experience for people who just want to come in and write documentation, potentially translate it, keep it up to date and accurate etc… to have to wade through TypeScript code to find what they need to do.

It’s just my opinion but it’s a poor developer, contributor and user experience mixing up UI pages and docs.

I’m just doing discovery on this now, as I think about it. Many months of discovery work ahead before making any decisions and planning more work here.

Speaking of discoveries look what I found:

The first repo created in the Teia Community org on GitHub. Forked from:

1 Like