Skip to main content

Documentation Quick Reference

Quick commands and tips for working with the R-TYPE J.A.M.E.S. documentation.

🚀 Quick Start​

# First time setup
cd docs
npm install

# Start development server
npm start

Visit the local site: http://localhost:3000/R_TYPE_J.A.M.E.S/

📝 Common Tasks​

View Documentation Locally​

cd docs && npm start

Build for Production​

cd docs && npm run build

Test Production Build​

cd docs && npm run build && npm run serve

Clear Cache (if having issues)​

cd docs && npm run clear

📄 Adding New Documentation​

Create a New Page​

  1. Create a new .md file in docs/docs/:
touch docs/docs/my-new-page.md
  1. Add front matter:
---
sidebar_position: 4
---

# My New Page

Content here...
  1. It will automatically appear in the sidebar!

Organizing Pages in Folders​

docs/docs/
├── intro.md
├── architecture.md
├── protocol.md
└── guides/
    ├── _category_.json
    ├── getting-started.md
    └── advanced.md

Create _category_.json:

{
  "label": "Guides",
  "position": 3,
  "link": {
    "type": "generated-index"
  }
}

🎨 Markdown Features​

Admonitions (Callouts)​

:::note
This is a note
:::

:::tip
Helpful tip here
:::

:::info
Information box
:::

:::warning
Warning message
:::

:::danger
Danger alert
:::

Code Blocks with Highlighting​

```cpp title="src/example.cpp" {1,3-5}
#include <iostream>

int main() {
    std::cout << "Hello, R-TYPE!" << std::endl;
    return 0;
}
```

Tabs​

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="linux" label="Linux" default>
    ```bash
    ./build/server/r-type_server
    ```
  </TabItem>
  <TabItem value="windows" label="Windows">
    ```bash
    .\build\server\r-type_server.exe
    ```
  </TabItem>
</Tabs>
[Internal Link](./architecture.md)
[External Link](https://github.com/MatthieuGA/R_TYPE_J.A.M.E.S.)

🔧 Configuration​

Update Site Metadata​

Edit docs/docusaurus.config.ts:

  • title: Site title
  • tagline: Subtitle
  • url: Production URL
  • baseUrl: Base path

Customize Theme​

Edit docs/src/css/custom.css:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  /* ... */
}

🚢 Deployment​

Manual Deploy​

cd docs
GIT_USER=<your-github-username> npm run deploy

Automatic (GitHub Actions)​

Just push to main branch. The workflow at .github/workflows/deploy-docs.yml will:

  1. Build the documentation
  2. Deploy to GitHub Pages

📊 File Structure Reference​

docs/
├── docs/               # Documentation pages (.md files)
├── src/
│   ├── components/    # Custom React components
│   ├── css/          # Custom styles
│   └── pages/        # Custom pages (e.g., home)
├── static/           # Static assets (images, files)
├── docusaurus.config.ts  # Main config
├── sidebars.ts       # Sidebar structure
└── package.json      # Dependencies

🐛 Troubleshooting​

Clear cache and reinstall​

cd docs
rm -rf node_modules package-lock.json .docusaurus
npm install
npm start

Port already in use​

npm start -- --port 3001

Build fails​

npm run clear
npm run build

📚 Learn More​

✅ Checklist for New Contributors​

  • Install Node.js 20+
  • Run npm install in docs/
  • Start dev server with npm start
  • Make your changes
  • Test locally
  • Build with npm run build to verify
  • Commit and push