tfgrid/docs_tfgrid_economics
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: TFGrid Economics documentation site
Some checks failed
Deploy to GitHub Pages / Deploy to GitHub Pages (push) Has been cancelled
Details

Browse Source 
- Based on working minting_plan repository
- Configured for threefold.info/economics deployment
- Added ops documentation for server deployment
- Updated baseUrl and URL configuration
This commit is contained in:
mik-tf
2025-10-10 21:38:17 -04:00
commit 65fbdb836b
32 changed files with 24403 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
docs/ops/local-development.md Normal file
View File

@@ -0,0 +1,391 @@
---
sidebar_position: 2
---
# Local Development
This guide covers how to set up and run the TFT Minting Transition Plan site locally for development and testing.
## Prerequisites
### Required Software
- **Node.js**: Version 18.0 or higher
- **npm**: Comes with Node.js
- **Git**: For version control
### Check Your Versions
```bash
node --version # Should be v18.0.0 or higher
npm --version # Should be 8.0.0 or higher
git --version # Any recent version
```
### Installing Node.js
If you don't have Node.js 18+:
**Linux (Ubuntu/Debian)**:
```bash
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
```
**macOS**:
```bash
brew install node@18
```
**Using nvm (recommended)**:
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
```
---
## Initial Setup
### 1. Clone the Repository
```bash
git clone https://github.com/mik-tf/minting_plan.git
cd minting_plan
```
### 2. Install Dependencies
```bash
npm install
```
This will install all required packages listed in `package.json`, including:
- Docusaurus core
- React
- MDX support
- Theme packages
:::info First Install
The first `npm install` will take 1-2 minutes as it downloads all dependencies. Subsequent installs will be faster thanks to npm cache.
:::
---
## Development Server
### Start the Dev Server
```bash
npm start
```
This command:
- Starts a local development server
- Opens your browser to `http://localhost:3000`
- Enables hot reloading (changes appear immediately)
- Shows build errors in the terminal and browser
### What You'll See
```
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/
```
:::tip Hot Reloading
Edit any markdown file and save - your browser will automatically refresh with changes. No need to restart the server!
:::
### Stop the Server
Press `Ctrl+C` in the terminal where the server is running.
---
## Building for Production
### Create Production Build
```bash
npm run build
```
This command:
- Creates optimized production files in `build/` directory
- Minifies JavaScript and CSS
- Generates static HTML for all pages
- Checks for broken links
### Preview Production Build
```bash
npm run serve
```
This serves the production build locally at `http://localhost:3000` so you can test it before deployment.
:::warning Test Before Push
Always run `npm run build` before pushing to ensure there are no build errors. The production build is stricter than dev mode.
:::
---
## Common Development Tasks
### Adding a New Page
1. Create a new `.md` file in the appropriate docs folder:
```bash
touch docs/core-concepts/new-concept.md
```
2. Add frontmatter:
```markdown
---
sidebar_position: 5
---
# New Concept Title
Your content here...
```
3. The page appears automatically in the sidebar!
### Editing Existing Content
1. Navigate to the file (e.g., `docs/intro.md`)
2. Make your changes
3. Save the file
4. Browser auto-refreshes with changes
### Adding Images
1. Place images in `static/img/`:
```bash
cp ~/my-image.png static/img/
```
2. Reference in markdown:
```markdown
![Alt text](./img/my-image.png)
```
---
## Project Structure
```
minting_plan/
├── docs/ # All documentation content
│ ├── intro.md # Homepage
│ ├── core-concepts/ # Core concept docs
│ ├── appendix/ # Meeting notes, etc.
│ └── ops/ # Operations guides
├── static/ # Static assets
│ ├── img/ # Images
│ └── CNAME # Custom domain file
├── src/ # Custom React components
│ ├── css/ # Custom styles
│ └── pages/ # Custom pages (optional)
├── docusaurus.config.js # Site configuration
├── sidebars.js # Sidebar structure
├── package.json # Dependencies
└── .github/workflows/ # GitHub Actions
└── deploy.yml # Auto-deployment
```
---
## Useful Commands
### Clear Cache
If you see weird behavior, clear the cache:
```bash
npm run clear
```
### Check for Build Issues
```bash
npm run build
```
Look for:
- ✅ Success: Build completed
- ❌ Errors: Broken links, invalid markdown, missing files
### Format Code (if using Prettier)
```bash
npx prettier --write "docs/**/*.md"
```
---
## Development Workflow
### Typical Workflow
1. **Pull latest changes**
```bash
git pull origin main
```
2. **Start dev server**
```bash
npm start
```
3. **Make changes**
- Edit markdown files in `docs/`
- See changes instantly in browser
4. **Test production build**
```bash
npm run build
```
5. **Commit and push**
```bash
git add .
git commit -m "Description of changes"
git push origin main
```
6. **Auto-deployment**
- GitHub Actions builds and deploys automatically
- Check Actions tab for status
- Site updates at plan.threefold.pro in ~3 minutes
---
## Troubleshooting
### Port 3000 Already in Use
**Error**: `Something is already running on port 3000`
**Solution**:
```bash
# Find and kill the process
lsof -i :3000
kill -9 <PID>
# Or use a different port
npm start -- --port 3001
```
### Module Not Found Errors
**Error**: `Cannot find module '@docusaurus/...'`
**Solution**:
```bash
# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
```
### Build Fails Locally
**Error**: Build fails with various errors
**Solution**:
```bash
# Clear cache and rebuild
npm run clear
npm run build
```
### Changes Not Appearing
**Problem**: Saved changes don't show in browser
**Solution**:
1. Check the terminal for build errors
2. Hard refresh browser: `Ctrl+Shift+R` (Linux/Win) or `Cmd+Shift+R` (Mac)
3. Restart dev server: `Ctrl+C`, then `npm start`
### Node Version Issues
**Error**: `The engine "node" is incompatible with this module`
**Solution**:
```bash
# Check your version
node --version
# Install correct version using nvm
nvm install 18
nvm use 18
```
---
## Best Practices
### Before Committing
✅ **Do**:
- Test build locally: `npm run build`
- Check for broken links in build output
- Preview with `npm run serve`
- Write clear commit messages
❌ **Don't**:
- Commit `node_modules/` (it's in .gitignore)
- Commit `build/` directory (it's generated)
- Push without testing build
- Use absolute URLs for internal links
### Writing Documentation
✅ **Good practices**:
- Use relative links: `[link](./other-page.md)`
- Add alt text to images: `![Description](./img/pic.png)`
- Use frontmatter for sidebar position
- Keep markdown files in appropriate folders
❌ **Avoid**:
- Absolute URLs for internal pages
- Missing alt text on images
- Inconsistent heading levels
- Very long lines (wrap at ~100 chars)
---
## IDE Setup
### VS Code (Recommended)
Install these extensions for better experience:
- **Markdown All in One**: Markdown preview and shortcuts
- **Prettier**: Code formatting
- **ESLint**: JavaScript linting
### Settings
Add to `.vscode/settings.json`:
```json
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"[markdown]": {
"editor.wordWrap": "on"
}
}
```
---
## Next Steps
- [Deployment](./deployment.md) - Deploy to plan.threefold.pro
- [Content Updates](./content-updates.md) - Learn content management workflows