---
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/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: `![](./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