nofx/docs/MIGRATION_GUIDE.md
tinkle-community 16ff57778d update docs
2025-12-21 01:36:16 +08:00

6.0 KiB

๐Ÿ“ฆ Documentation Migration Guide

What Changed?

NOFX documentation has been reorganized into a structured docs/ directory for better organization and navigation.

๐Ÿ—บ๏ธ File Locations (Old โ†’ New)

Deployment Guides

  • DOCKER_DEPLOY.en.md โ†’ docs/getting-started/docker-deploy.en.md
  • DOCKER_DEPLOY.md โ†’ docs/getting-started/docker-deploy.zh-CN.md
  • CUSTOM_API.md โ†’ docs/getting-started/custom-api.md

Community Docs

  • HOW_TO_POST_BOUNTY.md โ†’ docs/community/bounty-guide.md
  • INTEGRATION_BOUNTY_HYPERLIQUID.md โ†’ docs/community/bounty-hyperliquid.md
  • INTEGRATION_BOUNTY_ASTER.md โ†’ docs/community/bounty-aster.md

Internationalization

  • README.zh-CN.md โ†’ docs/i18n/zh-CN/README.md
  • README.ru.md โ†’ docs/i18n/ru/README.md
  • README.uk.md โ†’ docs/i18n/uk/README.md
  • ๅธธ่ง้—ฎ้ข˜.md โ†’ docs/guides/faq.zh-CN.md

Root Directory (Unchanged)

These stay in the root for GitHub recognition:

  • README.md โœ… (stays in root)
  • LICENSE โœ… (stays in root)
  • CONTRIBUTING.md โœ… (stays in root)
  • CODE_OF_CONDUCT.md โœ… (stays in root)
  • SECURITY.md โœ… (stays in root)

๐ŸŽฏ Why This Change?

Before (โŒ Problems)

nofx/
โ”œโ”€โ”€ README.md
โ”œโ”€โ”€ README.zh-CN.md
โ”œโ”€โ”€ README.ru.md
โ”œโ”€โ”€ README.uk.md
โ”œโ”€โ”€ DOCKER_DEPLOY.md
โ”œโ”€โ”€ DOCKER_DEPLOY.en.md
โ”œโ”€โ”€ CUSTOM_API.md
โ”œโ”€โ”€ HOW_TO_POST_BOUNTY.md
โ”œโ”€โ”€ INTEGRATION_BOUNTY_HYPERLIQUID.md
โ”œโ”€โ”€ INTEGRATION_BOUNTY_ASTER.md
โ”œโ”€โ”€ ๅธธ่ง้—ฎ้ข˜.md
โ””โ”€โ”€ ... (15+ markdown files in root!)

Issues:

  • ๐Ÿ˜ต Too cluttered (15+ files in root)
  • ๐Ÿ” Hard to find specific docs
  • ๐ŸŒ Mixed languages
  • ๐Ÿ“š No clear organization

After (โœ… Benefits)

nofx/
โ”œโ”€โ”€ README.md              # Project homepage
โ”œโ”€โ”€ LICENSE                # Legal (GitHub needs it here)
โ”œโ”€โ”€ CONTRIBUTING.md        # GitHub auto-links
โ”œโ”€โ”€ CODE_OF_CONDUCT.md     # GitHub auto-links
โ”œโ”€โ”€ SECURITY.md            # GitHub auto-links
โ”‚
โ””โ”€โ”€ docs/                  # ๐Ÿ“š Documentation hub
    โ”œโ”€โ”€ README.md          # Documentation home
    โ”œโ”€โ”€ getting-started/   # ๐Ÿš€ Setup guides
    โ”œโ”€โ”€ guides/            # ๐Ÿ“˜ User guides
    โ”œโ”€โ”€ community/         # ๐Ÿ‘ฅ Contribution docs
    โ”œโ”€โ”€ i18n/              # ๐ŸŒ Translations
    โ””โ”€โ”€ architecture/      # ๐Ÿ—๏ธ Technical docs

Benefits:

  • โœ… Clean root directory
  • โœ… Logical categorization
  • โœ… Easy navigation
  • โœ… Scalable structure
  • โœ… Professional appearance

๐Ÿ“š New Documentation Structure

Root Level

Files GitHub needs to see:

  • README.md - Main project page
  • LICENSE - Open source license
  • CONTRIBUTING.md - Contributor guide
  • CODE_OF_CONDUCT.md - Community standards
  • SECURITY.md - Security policy

docs/ Level

Navigation:

  • docs/README.md - Start here! Main documentation hub

Categories:

  1. getting-started/ - Deployment and setup

    • Docker deployment (EN/ไธญๆ–‡)
    • Custom API configuration
  2. guides/ - Usage guides and tutorials

    • FAQ (ไธญๆ–‡)
    • Troubleshooting (planned)
    • Configuration examples (planned)
  3. community/ - Contribution and bounties

    • Bounty guide
    • Active bounty tasks
    • Contributor recognition
  4. i18n/ - International translations

    • zh-CN/ - Simplified Chinese
    • ru/ - Russian
    • uk/ - Ukrainian
  5. architecture/ - Technical documentation

    • System design (planned)
    • API reference (planned)
    • Database schema (planned)
Old Link New Link
DOCKER_DEPLOY.en.md docs/getting-started/docker-deploy.en.md
README.zh-CN.md docs/i18n/zh-CN/README.md
HOW_TO_POST_BOUNTY.md docs/community/bounty-guide.md

If you linked in your own docs:

Update relative links:

<!-- Old -->
[Docker Deployment](DOCKER_DEPLOY.en.md)

<!-- New -->
[Docker Deployment](docs/getting-started/docker-deploy.en.md)

GitHub URLs automatically redirect!

  • Old: github.com/NoFxAiOS/nofx/blob/main/DOCKER_DEPLOY.en.md
  • Will redirect to: github.com/.../docs/getting-started/docker-deploy.en.md

๐Ÿ› ๏ธ For Contributors

Cloning/Pulling Latest

# Pull latest changes
git pull origin dev

# Your old bookmarks still work!
# Git tracked the file moves (git mv)

Finding Documentation

Use the navigation hub:

  1. Start at docs/README.md
  2. Browse by category
  3. Use the quick navigation section

Or search:

# Find all markdown docs
find docs -name "*.md"

# Search content
grep -r "keyword" docs/

Adding New Documentation

Follow the structure:

# Getting started guides
docs/getting-started/your-guide.md

# User guides
docs/guides/your-tutorial.md

# Community docs
docs/community/your-doc.md

# Translations
docs/i18n/ja/README.md  # Japanese example

Update navigation:

  • Add link in relevant category README
  • Add to docs/README.md main hub

๐Ÿ“ Commit Messages

This reorganization was committed as:

docs: reorganize documentation into structured docs/ directory

- Move deployment guides to docs/getting-started/
- Move community docs to docs/community/
- Move translations to docs/i18n/
- Create navigation hub at docs/README.md
- Update all internal links in README.md
- Add GitHub issue/PR templates

BREAKING CHANGE: Direct links to moved files will need updating
(though GitHub redirects should work)

Closes #XXX

๐Ÿ†˜ Need Help?

Can't find a document?

  1. Check docs/README.md navigation hub
  2. Search GitHub repo
  3. Ask in Telegram

Link broken?

Want to contribute docs?


Migration Date: 2025-11-01 Maintainers: Tinkle Community

โ† Back to Documentation Home