Files

Deploy to GitHub Pages / Deploy to GitHub Pages (push) Has been cancelled

Details

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

9.6 KiB

Raw Blame History

sidebar_position

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:

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

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:

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',
}

Add to Footer

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