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:

---
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

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

# 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:

---
sidebar_position: 5
title: Custom Page Title (optional)
---

# New Topic

Your content here...

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:

The folder it's in
The sidebar_position value
The first heading (#) as the title

Working with Images

Adding Images

Place image in static folder:
```
cp ~/Downloads/diagram.png static/img/
```

Reference in 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:

{
  "label": "Core Concepts",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "Overview description here."
  }
}

Moving Pages

To move a page to a different section:

Move the file:

mv docs/core-concepts/old.md docs/appendix/old.md

Update any links to it in other pages
Test build: npm run build

Markdown Features

Basic Syntax

# 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

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |
| Data     | Data     | Data     |

Code Blocks

```javascript
const example = "code block with syntax highlighting";
```

```bash
npm install
npm start
```

Admonitions

:::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:

<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:

[See Token System](./token-system.md)

To different folder:

[See Deployment Guide](../ops/deployment.md)

Using path from root:

[See Deployment Guide](/ops/deployment)

External Links

[ThreeFold](https://threefold.io)
[Forum](https://forum.threefold.io)

External links automatically open in new tabs.

Link Checking

Build process checks for broken links:

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:

<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:

{
  href: 'https://t.me/threefoldfarmers',
  label: 'Telegram',
  position: 'right',
}

Edit docusaurus.config.js footer section:

footer: {
  links: [
    {
      title: 'New Section',
      items: [
        {
          label: 'New Link',
          href: 'https://example.com',
        },
      ],
    },
  ],
}

Update Announcement Bar

Edit docusaurus.config.js:

announcementBar: {
  id: 'new_announcement',
  content: 'Your new announcement here!',
  backgroundColor: '#20232a',
  textColor: '#fff',
  isCloseable: true,
}

Content Workflow

Standard Update Process

Create a branch (optional but recommended):
```
git checkout -b update-intro-page
```
Make changes:
- Edit markdown files
- Add/update images
- Test locally: npm start
Test build:
```
npm run build
npm run serve
```

Commit changes:

git add .
git commit -m "Update intro page with new questions"

Push to GitHub:

git push origin update-intro-page
# Or if working directly on main:
git push origin main

Create Pull Request (if using branches):
- Go to GitHub repository
- Click "Pull Requests" → "New Pull Request"
- Review changes, merge to main
Automatic deployment:
- GitHub Actions builds and deploys
- Monitor in Actions tab
- Live in ~3 minutes

Multiple Contributors

Collaborative Workflow

Before starting work:

git pull origin main

After your changes:

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:

# 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:

npm run build

Error messages show the problem file and line number.

Changes Don't Appear Live

Possible causes:

Build failed - Check GitHub Actions tab
Cache issue - Hard refresh browser: Ctrl+Shift+R
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/:

// src/components/CustomCard.js
export default function CustomCard({title, children}) {
  return (
    <div className="custom-card">
      <h3>{title}</h3>
      {children}
    </div>
  );
}

Use in 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:

npm run docusaurus docs:version 1.0

This creates a snapshot of current docs as version 1.0.

Next Steps

Deployment Guide - Deploy changes to production
Local Development - Set up your dev environment

Quick Reference​

Editing Existing Pages​

1. Locate the File​

2. Make Your Changes​

3. Preview Changes​

4. Deploy​

Adding New Pages​

Create the File​

Add Frontmatter​

Sidebar Position​

The Page Appears Automatically!​

Working with Images​

Adding Images​

Image Best Practices​

Image Locations​

Organizing Content​

Category Structure​

Moving Pages​

Markdown Features​

Basic Syntax​

Tables​

Code Blocks​

Admonitions​

Custom Styles​

Link Management​

Internal Links​

External Links​

Link Checking​

Common Content Tasks​

Update Open Questions (Intro Page)​

Update Community Links​

Add to Footer​

Update Announcement Bar​

Content Workflow​

Standard Update Process​

Multiple Contributors​

Collaborative Workflow​

Handling Conflicts​

Content Guidelines​

Writing Style​

Formatting Consistency​

Accessibility​

Troubleshooting​

Build Fails After Edit​

Changes Don't Appear Live​

Images Not Loading​

Advanced Topics​

Custom React Components​

Custom Styling​

Versioning (Future)​

Next Steps​