Initial commit: TFGrid Economics documentation site

- Based on working minting_plan repository - Configured for threefold.info/economics deployment - Added ops documentation for server deployment - Updated baseUrl and URL configuration
2025-10-10 21:38:17 -04:00
commit 65fbdb836b
32 changed files with 24403 additions and 0 deletions
--- a/docs/ops/content-updates.md
+++ b/docs/ops/content-updates.md
@@ -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 `![](./img/name.png)` |
+| 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
+   ![Diagram Description](./img/diagram.png)
+   ```
+
+### Image Best Practices
+
+✅ **Do**:
+- Use descriptive filenames: `token-flow-diagram.png`
+- Add alt text: `![Token Flow Diagram](./img/token-flow.png)`
+- Optimize images (compress before adding)
+- Use PNG for diagrams, JPG for photos
+
+❌ **Don't**:
+- Use absolute paths: `![](/static/img/pic.png)` ❌
+- Skip alt text: `![](./img/pic.png)` ❌
+- 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/threefoldfarmers',
+  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: `![](./img/name.png)`
+- 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