This commit is contained in:
8
docsarchive/ops/_category_.json
Normal file
8
docsarchive/ops/_category_.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Operations",
|
||||
"position": 4,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Technical documentation for deployment, development, and content management."
|
||||
}
|
||||
}
|
||||
586
docsarchive/ops/content-updates.md
Normal file
586
docsarchive/ops/content-updates.md
Normal file
@@ -0,0 +1,586 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Content Updates
|
||||
|
||||
This guide covers how to update content, add new documentation, and manage the site structure.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Action |
|
||||
|------|--------|
|
||||
| Edit existing page | Modify `.md` file in `docs/` |
|
||||
| Add new page | Create new `.md` file with frontmatter |
|
||||
| Add image | Place in `static/img/`, reference with `` |
|
||||
| Update navigation | Edit `sidebars.js` or frontmatter |
|
||||
| Deploy changes | Push to `main` branch |
|
||||
|
||||
---
|
||||
|
||||
## Editing Existing Pages
|
||||
|
||||
### 1. Locate the File
|
||||
|
||||
All documentation lives in `docs/`:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── intro.md # Homepage content
|
||||
├── core-concepts/
|
||||
│ ├── token-system.md
|
||||
│ ├── position-based-lp.md
|
||||
│ ├── dutch-auction-exit.md
|
||||
│ └── yin-yang-currency.md
|
||||
└── ops/
|
||||
├── deployment.md
|
||||
├── local-development.md
|
||||
└── content-updates.md # This file
|
||||
```
|
||||
|
||||
### 2. Make Your Changes
|
||||
|
||||
Open the file in your text editor and modify the markdown:
|
||||
|
||||
```markdown
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Page Title
|
||||
|
||||
Your content here in **Markdown** format.
|
||||
|
||||
- Bullet points
|
||||
- More bullets
|
||||
|
||||
## Subheading
|
||||
|
||||
More content...
|
||||
```
|
||||
|
||||
### 3. Preview Changes
|
||||
|
||||
If running dev server (`npm start`), changes appear immediately in your browser.
|
||||
|
||||
### 4. Deploy
|
||||
|
||||
```bash
|
||||
git add docs/intro.md
|
||||
git commit -m "Update introduction page"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
GitHub Actions automatically builds and deploys in ~3 minutes.
|
||||
|
||||
---
|
||||
|
||||
## Adding New Pages
|
||||
|
||||
### Create the File
|
||||
|
||||
```bash
|
||||
# Add to core concepts
|
||||
touch docs/core-concepts/new-topic.md
|
||||
|
||||
# Or to node economics
|
||||
touch docs/node-economics/new-resource.md
|
||||
```
|
||||
|
||||
### Add Frontmatter
|
||||
|
||||
Every page needs frontmatter at the top:
|
||||
|
||||
```markdown
|
||||
---
|
||||
sidebar_position: 5
|
||||
title: Custom Page Title (optional)
|
||||
---
|
||||
|
||||
# New Topic
|
||||
|
||||
Your content here...
|
||||
```
|
||||
|
||||
### Sidebar Position
|
||||
|
||||
- Lower numbers appear first (1, 2, 3...)
|
||||
- Pages without position appear after numbered pages
|
||||
- Categories have their own positions
|
||||
|
||||
### The Page Appears Automatically!
|
||||
|
||||
Docusaurus automatically adds the page to the sidebar based on:
|
||||
1. The folder it's in
|
||||
2. The `sidebar_position` value
|
||||
3. The first heading (`#`) as the title
|
||||
|
||||
---
|
||||
|
||||
## Working with Images
|
||||
|
||||
### Adding Images
|
||||
|
||||
1. **Place image in static folder:**
|
||||
```bash
|
||||
cp ~/Downloads/diagram.png static/img/
|
||||
```
|
||||
|
||||
2. **Reference in markdown:**
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
### Image Best Practices
|
||||
|
||||
✅ **Do**:
|
||||
- Use descriptive filenames: `token-flow-diagram.png`
|
||||
- Add alt text: ``
|
||||
- Optimize images (compress before adding)
|
||||
- Use PNG for diagrams, JPG for photos
|
||||
|
||||
❌ **Don't**:
|
||||
- Use absolute paths: `` ❌
|
||||
- Skip alt text: `` ❌
|
||||
- Use huge unoptimized images (slow loading)
|
||||
|
||||
### Image Locations
|
||||
|
||||
```
|
||||
static/img/
|
||||
├── logo.png # Site logo
|
||||
├── margin_distribution.png # Dutch auction images
|
||||
└── margin_distribution_1.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Organizing Content
|
||||
|
||||
### Category Structure
|
||||
|
||||
Each folder can have a `_category_.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "Core Concepts",
|
||||
"position": 2,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Overview description here."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Moving Pages
|
||||
|
||||
To move a page to a different section:
|
||||
|
||||
1. Move the file:
|
||||
```bash
|
||||
mv docs/core-concepts/old.md docs/appendix/old.md
|
||||
```
|
||||
|
||||
2. Update any links to it in other pages
|
||||
|
||||
3. Test build: `npm run build`
|
||||
|
||||
---
|
||||
|
||||
## Markdown Features
|
||||
|
||||
### Basic Syntax
|
||||
|
||||
```markdown
|
||||
# Heading 1
|
||||
## Heading 2
|
||||
### Heading 3
|
||||
|
||||
**Bold text**
|
||||
*Italic text*
|
||||
|
||||
[Link text](./other-page.md)
|
||||
[External link](https://example.com)
|
||||
|
||||
- Bullet list
|
||||
- More bullets
|
||||
|
||||
1. Numbered list
|
||||
2. More numbers
|
||||
```
|
||||
|
||||
### Tables
|
||||
|
||||
```markdown
|
||||
| Column 1 | Column 2 | Column 3 |
|
||||
|----------|----------|----------|
|
||||
| Data | Data | Data |
|
||||
| Data | Data | Data |
|
||||
```
|
||||
|
||||
### Code Blocks
|
||||
|
||||
````markdown
|
||||
```javascript
|
||||
const example = "code block with syntax highlighting";
|
||||
```
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
````
|
||||
|
||||
### Admonitions
|
||||
|
||||
```markdown
|
||||
:::note
|
||||
This is a note
|
||||
:::
|
||||
|
||||
:::tip
|
||||
This is a tip
|
||||
:::
|
||||
|
||||
:::info
|
||||
This is info
|
||||
:::
|
||||
|
||||
:::warning
|
||||
This is a warning
|
||||
:::
|
||||
|
||||
:::danger
|
||||
This is danger
|
||||
:::
|
||||
```
|
||||
|
||||
### Custom Styles
|
||||
|
||||
The site includes custom CSS classes:
|
||||
|
||||
```markdown
|
||||
<div className="feedback-box">
|
||||
|
||||
### Special Feedback Section
|
||||
|
||||
With custom styling!
|
||||
|
||||
</div>
|
||||
|
||||
<div className="open-questions">
|
||||
|
||||
### Open Questions
|
||||
|
||||
Highlighted questions section
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Link Management
|
||||
|
||||
### Internal Links
|
||||
|
||||
**Between pages in same folder:**
|
||||
```markdown
|
||||
[See Token System](./token-system.md)
|
||||
```
|
||||
|
||||
**To different folder:**
|
||||
```markdown
|
||||
[See Deployment Guide](../ops/deployment.md)
|
||||
```
|
||||
|
||||
**Using path from root:**
|
||||
```markdown
|
||||
[See Deployment Guide](/ops/deployment)
|
||||
```
|
||||
|
||||
### External Links
|
||||
|
||||
```markdown
|
||||
[ThreeFold](https://threefold.io)
|
||||
[Forum](https://forum.threefold.io)
|
||||
```
|
||||
|
||||
External links automatically open in new tabs.
|
||||
|
||||
### Link Checking
|
||||
|
||||
Build process checks for broken links:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Look for warnings about broken links in output.
|
||||
|
||||
---
|
||||
|
||||
## Common Content Tasks
|
||||
|
||||
### Update Open Questions (Intro Page)
|
||||
|
||||
Edit `docs/intro.md`, find the open questions section:
|
||||
|
||||
```markdown
|
||||
<div className="open-questions">
|
||||
|
||||
### Key Areas We're Seeking Feedback On:
|
||||
|
||||
- **Entry Price**: Should the fixed TFT to CC conversion rate be...
|
||||
- **New Question**: Add your new question here
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
### Update Community Links
|
||||
|
||||
Edit `docusaurus.config.js`:
|
||||
|
||||
```javascript
|
||||
{
|
||||
href: 'https://t.me/threefoldhosters',
|
||||
label: 'Telegram',
|
||||
position: 'right',
|
||||
}
|
||||
```
|
||||
|
||||
### Add to Footer
|
||||
|
||||
Edit `docusaurus.config.js` footer section:
|
||||
|
||||
```javascript
|
||||
footer: {
|
||||
links: [
|
||||
{
|
||||
title: 'New Section',
|
||||
items: [
|
||||
{
|
||||
label: 'New Link',
|
||||
href: 'https://example.com',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
### Update Announcement Bar
|
||||
|
||||
Edit `docusaurus.config.js`:
|
||||
|
||||
```javascript
|
||||
announcementBar: {
|
||||
id: 'new_announcement',
|
||||
content: 'Your new announcement here!',
|
||||
backgroundColor: '#20232a',
|
||||
textColor: '#fff',
|
||||
isCloseable: true,
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Workflow
|
||||
|
||||
### Standard Update Process
|
||||
|
||||
1. **Create a branch (optional but recommended):**
|
||||
```bash
|
||||
git checkout -b update-intro-page
|
||||
```
|
||||
|
||||
2. **Make changes:**
|
||||
- Edit markdown files
|
||||
- Add/update images
|
||||
- Test locally: `npm start`
|
||||
|
||||
3. **Test build:**
|
||||
```bash
|
||||
npm run build
|
||||
npm run serve
|
||||
```
|
||||
|
||||
4. **Commit changes:**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Update intro page with new questions"
|
||||
```
|
||||
|
||||
5. **Push to GitHub:**
|
||||
```bash
|
||||
git push origin update-intro-page
|
||||
# Or if working directly on main:
|
||||
git push origin main
|
||||
```
|
||||
|
||||
6. **Create Pull Request (if using branches):**
|
||||
- Go to GitHub repository
|
||||
- Click "Pull Requests" → "New Pull Request"
|
||||
- Review changes, merge to main
|
||||
|
||||
7. **Automatic deployment:**
|
||||
- GitHub Actions builds and deploys
|
||||
- Monitor in Actions tab
|
||||
- Live in ~3 minutes
|
||||
|
||||
---
|
||||
|
||||
## Multiple Contributors
|
||||
|
||||
### Collaborative Workflow
|
||||
|
||||
**Before starting work:**
|
||||
```bash
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
**After your changes:**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Clear description of changes"
|
||||
git pull origin main # Get any new changes
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### Handling Conflicts
|
||||
|
||||
If you get a merge conflict:
|
||||
|
||||
```bash
|
||||
# Open the conflicted file
|
||||
# Look for conflict markers:
|
||||
<<<<<<< HEAD
|
||||
Your changes
|
||||
=======
|
||||
Their changes
|
||||
>>>>>>> main
|
||||
|
||||
# Resolve by choosing one or combining both
|
||||
# Then:
|
||||
git add resolved-file.md
|
||||
git commit -m "Resolve merge conflict"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
### Writing Style
|
||||
|
||||
✅ **Do**:
|
||||
- Write clear, concise sentences
|
||||
- Use active voice
|
||||
- Break up long paragraphs
|
||||
- Add examples where helpful
|
||||
- Use headings to organize
|
||||
|
||||
❌ **Avoid**:
|
||||
- Jargon without explanation
|
||||
- Very long paragraphs
|
||||
- Walls of text
|
||||
- Broken links
|
||||
|
||||
### Formatting Consistency
|
||||
|
||||
- Use `**bold**` for emphasis
|
||||
- Use `*italic*` for terminology
|
||||
- Use `` `code` `` for commands, filenames, code
|
||||
- Use proper heading hierarchy (H1 → H2 → H3)
|
||||
|
||||
### Accessibility
|
||||
|
||||
- Add alt text to all images
|
||||
- Use descriptive link text (not "click here")
|
||||
- Maintain proper heading structure
|
||||
- Ensure good color contrast
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails After Edit
|
||||
|
||||
**Check for:**
|
||||
- Broken markdown syntax
|
||||
- Invalid frontmatter
|
||||
- Broken links: `[text](./wrong-file.md)`
|
||||
- Unclosed code blocks
|
||||
- Special characters in YAML frontmatter
|
||||
|
||||
**Test locally:**
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Error messages show the problem file and line number.
|
||||
|
||||
### Changes Don't Appear Live
|
||||
|
||||
**Possible causes:**
|
||||
1. **Build failed** - Check GitHub Actions tab
|
||||
2. **Cache issue** - Hard refresh browser: Ctrl+Shift+R
|
||||
3. **Deployment lag** - Wait 3-5 minutes after push
|
||||
|
||||
### Images Not Loading
|
||||
|
||||
**Check:**
|
||||
- Image is in `static/img/`
|
||||
- Path is correct: ``
|
||||
- Image filename matches exactly (case-sensitive)
|
||||
- Image was committed: `git add static/img/name.png`
|
||||
|
||||
---
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Custom React Components
|
||||
|
||||
Place in `src/components/`:
|
||||
|
||||
```jsx
|
||||
// src/components/CustomCard.js
|
||||
export default function CustomCard({title, children}) {
|
||||
return (
|
||||
<div className="custom-card">
|
||||
<h3>{title}</h3>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Use in markdown:
|
||||
|
||||
```markdown
|
||||
import CustomCard from '@site/src/components/CustomCard';
|
||||
|
||||
<CustomCard title="My Card">
|
||||
Content here
|
||||
</CustomCard>
|
||||
```
|
||||
|
||||
### Custom Styling
|
||||
|
||||
Edit `src/css/custom.css` to add global styles.
|
||||
|
||||
### Versioning (Future)
|
||||
|
||||
When ready to version docs:
|
||||
|
||||
```bash
|
||||
npm run docusaurus docs:version 1.0
|
||||
```
|
||||
|
||||
This creates a snapshot of current docs as version 1.0.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Deployment Guide](./deployment.md) - Deploy changes to production
|
||||
- [Local Development](./local-development.md) - Set up your dev environment
|
||||
298
docsarchive/ops/deployment.md
Normal file
298
docsarchive/ops/deployment.md
Normal file
@@ -0,0 +1,298 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Deployment to plan.threefold.pro
|
||||
|
||||
This guide covers how to deploy the TFT Minting Transition Plan site to the custom domain `plan.threefold.pro` using GitHub Pages.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- GitHub repository: `https://github.com/mik-tf/minting_plan`
|
||||
- Access to DNS provider for `threefold.pro` domain
|
||||
- GitHub Pages enabled on the repository
|
||||
- Node.js 18+ installed locally (for testing before deployment)
|
||||
|
||||
---
|
||||
|
||||
## DNS Configuration
|
||||
|
||||
Configure your DNS settings at your domain provider to point `plan.threefold.pro` to GitHub Pages.
|
||||
|
||||
### Option 1: CNAME Record (Recommended)
|
||||
|
||||
Add the following DNS record:
|
||||
|
||||
```
|
||||
Type: CNAME
|
||||
Name: plan
|
||||
Value: mik-tf.github.io
|
||||
TTL: 3600 (or your provider's default)
|
||||
```
|
||||
|
||||
### Option 2: A Records (Alternative)
|
||||
|
||||
If your DNS provider doesn't support CNAME for subdomains, use A records:
|
||||
|
||||
```
|
||||
Type: A
|
||||
Name: plan
|
||||
Value: 185.199.108.153
|
||||
TTL: 3600
|
||||
|
||||
Type: A
|
||||
Name: plan
|
||||
Value: 185.199.109.153
|
||||
TTL: 3600
|
||||
|
||||
Type: A
|
||||
Name: plan
|
||||
Value: 185.199.110.153
|
||||
TTL: 3600
|
||||
|
||||
Type: A
|
||||
Name: plan
|
||||
Value: 185.199.111.153
|
||||
TTL: 3600
|
||||
```
|
||||
|
||||
:::tip DNS Propagation
|
||||
DNS changes can take anywhere from 5 minutes to 48 hours to propagate globally. Typically it's 15-30 minutes.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## GitHub Repository Settings
|
||||
|
||||
### 1. Enable GitHub Pages
|
||||
|
||||
1. Go to your repository: `https://github.com/mik-tf/minting_plan`
|
||||
2. Click **Settings** → **Pages** (left sidebar)
|
||||
3. Under "Source", select:
|
||||
- **Branch**: `gh-pages`
|
||||
- **Folder**: `/ (root)`
|
||||
4. Click **Save**
|
||||
|
||||
### 2. Configure Custom Domain
|
||||
|
||||
1. Still in the Pages settings
|
||||
2. Under "Custom domain", enter: `plan.threefold.pro`
|
||||
3. Click **Save**
|
||||
4. Wait for DNS check (green checkmark ✓ will appear)
|
||||
5. Once verified, check **Enforce HTTPS** (automatic SSL certificate)
|
||||
|
||||
:::warning Important
|
||||
The CNAME file in the `static/` folder ensures the custom domain persists after each deployment. Don't delete it!
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## GitHub Actions Workflow
|
||||
|
||||
The repository includes an automated deployment workflow at `.github/workflows/deploy.yml`. This workflow:
|
||||
|
||||
- Triggers automatically on push to `main` branch
|
||||
- Installs dependencies
|
||||
- Builds the Docusaurus site
|
||||
- Deploys to `gh-pages` branch
|
||||
|
||||
### How It Works
|
||||
|
||||
```yaml
|
||||
name: Deploy to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 18
|
||||
cache: npm
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
- name: Build website
|
||||
run: npm run build
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./build
|
||||
```
|
||||
|
||||
### Manual Deployment (if needed)
|
||||
|
||||
If you need to deploy manually:
|
||||
|
||||
```bash
|
||||
# Build the site
|
||||
npm run build
|
||||
|
||||
# Deploy to GitHub Pages
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
:::info Automatic Deployment
|
||||
With GitHub Actions, you don't need to manually deploy. Just push to `main` and the site updates automatically in 2-3 minutes.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Verification Steps
|
||||
|
||||
After deployment, verify everything works:
|
||||
|
||||
### 1. Check GitHub Actions
|
||||
|
||||
1. Go to repository → **Actions** tab
|
||||
2. Verify the latest workflow run succeeded (green checkmark)
|
||||
3. If failed, click to see error logs
|
||||
|
||||
### 2. Check GitHub Pages Status
|
||||
|
||||
1. Go to repository → **Settings** → **Pages**
|
||||
2. You should see: "Your site is live at https://plan.threefold.pro"
|
||||
3. Green checkmark next to custom domain
|
||||
|
||||
### 3. Test the Website
|
||||
|
||||
Visit these URLs and verify they work:
|
||||
|
||||
- https://plan.threefold.pro (homepage/intro)
|
||||
- https://plan.threefold.pro/core-concepts/token-system
|
||||
- https://plan.threefold.pro/ops/deployment (this page!)
|
||||
|
||||
### 4. Verify SSL Certificate
|
||||
|
||||
- Ensure the site loads with `https://` (not `http://`)
|
||||
- Check browser shows padlock icon (secure connection)
|
||||
- Certificate should be issued by GitHub
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### DNS Not Resolving
|
||||
|
||||
**Symptoms**: Site doesn't load, "DNS_PROBE_FINISHED_NXDOMAIN" error
|
||||
|
||||
**Solutions**:
|
||||
1. Wait longer for DNS propagation (up to 48 hours)
|
||||
2. Check DNS records are correct using:
|
||||
```bash
|
||||
dig plan.threefold.pro
|
||||
```
|
||||
3. Try accessing from different network/device (might be local DNS cache)
|
||||
4. Flush your local DNS cache:
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemd-resolve --flush-caches
|
||||
|
||||
# macOS
|
||||
sudo dscacheutil -flushcache
|
||||
```
|
||||
|
||||
### 404 Errors
|
||||
|
||||
**Symptoms**: Homepage loads but inner pages show 404
|
||||
|
||||
**Solutions**:
|
||||
1. Verify `trailingSlash: false` in `docusaurus.config.js`
|
||||
2. Check GitHub Pages is deploying from `gh-pages` branch root
|
||||
3. Wait a few minutes after deployment completes
|
||||
|
||||
### Build Failures
|
||||
|
||||
**Symptoms**: GitHub Actions workflow fails
|
||||
|
||||
**Solutions**:
|
||||
1. Check Actions tab for error logs
|
||||
2. Verify `package.json` has correct dependencies
|
||||
3. Test build locally: `npm run build`
|
||||
4. Check for broken links in markdown files
|
||||
|
||||
### Custom Domain Not Persisting
|
||||
|
||||
**Symptoms**: Custom domain resets after deployment
|
||||
|
||||
**Solutions**:
|
||||
1. Ensure `static/CNAME` file exists with content: `plan.threefold.pro`
|
||||
2. The CNAME file should be committed to git
|
||||
3. After build, verify `build/CNAME` exists
|
||||
|
||||
---
|
||||
|
||||
## Deployment Timeline
|
||||
|
||||
Understanding what happens when you push changes:
|
||||
|
||||
| Time | Event |
|
||||
|------|-------|
|
||||
| T+0s | Push commit to `main` branch |
|
||||
| T+10s | GitHub Actions workflow starts |
|
||||
| T+2min | Build completes, deploys to `gh-pages` branch |
|
||||
| T+3min | GitHub Pages processes update |
|
||||
| T+5min | Site live at plan.threefold.pro |
|
||||
|
||||
:::tip Quick Updates
|
||||
For urgent fixes, monitor the Actions tab to see when deployment completes, then verify changes immediately.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### HTTPS/SSL
|
||||
- GitHub Pages provides automatic SSL via Let's Encrypt
|
||||
- Certificate renews automatically
|
||||
- Always enforce HTTPS in settings
|
||||
|
||||
### Branch Protection
|
||||
Consider protecting the `main` branch:
|
||||
1. Settings → Branches → Add rule
|
||||
2. Require pull request reviews
|
||||
3. Require status checks to pass
|
||||
|
||||
### Access Control
|
||||
- Only repository collaborators can push to `main`
|
||||
- Manage access in Settings → Collaborators
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regular Updates
|
||||
|
||||
Keep Docusaurus and dependencies updated:
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
npm outdated
|
||||
|
||||
# Update dependencies
|
||||
npm update
|
||||
|
||||
# Update Docusaurus to latest
|
||||
npm install @docusaurus/core@latest @docusaurus/preset-classic@latest
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
Monitor these regularly:
|
||||
- GitHub Actions workflow status
|
||||
- Site accessibility at plan.threefold.pro
|
||||
- SSL certificate validity (automatic but good to check)
|
||||
- Build times (should stay under 3 minutes)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Local Development](./local-development.md) - Test changes before deploying
|
||||
- [Content Updates](./content-updates.md) - How to edit and add content
|
||||
391
docsarchive/ops/local-development.md
Normal file
391
docsarchive/ops/local-development.md
Normal 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
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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: ``
|
||||
- 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
|
||||
Reference in New Issue
Block a user