filecoin-project / filecoin-docs

This repository manages the documentation for the Filecoin network. This repo also contains the build scripts and tools to create the Filecoin docs website. Explore the docs →

Table of contents

• Getting started
  • Prerequisites
  • Installation
• About the project
  • Files and folders
• Contributing
  • Video guides for site management
  • Front-matter variables
    • Title
    • Description
    • Lead
    • Weight
    • Menu
      • Sidebar menu
      • Sub-menu
    • Aliases
    • Draft
  • Features
    • Archived content
    • Code tabs
    • Tooltips
• Issues
• License
• Acknowledgments

Getting Started

Follow these simple example steps to get a local version of the site up and running.

Prerequisites

To run these commands, you must have NPM installed. If you already have NPM installed, make sure you are running the latest version:

npm install npm@latest -g

Installation

Follow these steps to run a copy of this site on your local computer.

1. Clone this repo:

   git clone https://github.com/filecoin-project/filecoin-docs

2. Move into the new folder and download the dependencies:

   cd filecoin-docs
   npm install

3. Build and serve the project locally:

   npm run start

4. Visit localhost:1313 to view the site.

5. Press CTRL + c in the terminal to stop the local server.

If you want to just build the site but not serve it locally, run:

npm run build

A static site will be built and stored in the /public directory.

About the project

This repository manages the documentation for the Filecoin project. This repo also contains the build scripts and tools to create the Filecoin docs website and the API documentation. If you want to learn about Filecoin, how it works, or how to build on it, then you're in the right place.

Files and folders

This section lists the various files and folders and defines the purpose for each of them.

Contributing

Want to help out? Pull requests (PRs) are always welcome! If you want to help out but aren't sure where to start, check out the issues board.

Video guides for site management

Here's a collection of guides you can use to help manage and contribute to this site:

• Managing the top-bar navigation
• Move a page and add a redirect

Creating sidebar labels and content pages

To create sidebar labels, use the npm create command:

npm run create -- --kind sidebar storage-provider/hardware 

The above command will create the folder structure and a _index.md file containing the front-matter for the label.

Creating content pages

To create content pages, use the npm create command:

npm run create -- --kind page storage-provider/hardware/architectures

The above command will create a folder and an index.md file containing the front-matter for that page, that can then be edited.

If you make a mistake and need to remove a page, or section, just delete the folder.

To move content from one place to another, create the new pages using npm create, copy the text across to the newly created pages and delete the originals.

Front-matter variables

The front-matter is that small section of metadata you can find at the top of each .md file within the /content folder. Each variable has a specific purpose, and while not all are necessary, it's useful to know what they do and why they exist.

---
title: "Get started"
description: "The Filecoin Network is made with storage providers and clients. They make deals and contribute to maintaining the Filecoin blockchain, obtaining storage services, and receiving rewards in the process. This section walks you through how to get started, build a node, and create a simple application."
lead: "The Filecoin Network is made with storage providers and clients. They make deals and contribute to maintaining the Filecoin blockchain, obtaining storage services, and receiving rewards in the process. This section walks your through how to get started, build a node, and create a simple application."
menu:
    getstarted:
        parent: "getstarted-overview"
aliases:
    - /get-started
    - /how-to/install-filecoin
---

It's also good to note that we use the YAML as our front-matter format. We could use JSON or TOML if we really wanted, but we found YAML the easiest to read. Plus, yammal is fun to say.

This list has been created in order of commonality; variables you will come across most often are closer to the top of this list.

Title

The title variable defines what the <h1> tag on this page will say, along with the contents of <title> in this page's <head>. This variable also defines what is shown as the sidebar item; however, this can be overwritten in the menus config file.

---
title: "Get started"
---

Description

The description variable defines what is in the meta <description> tag within the <head> tag of this page's HTML. This description often shows up in search engine results, and social network embeds. This description is meant to give the reader an idea of the content on this page and how it relates to their search query.

---
description: "The Filecoin Network is made with storage providers and clients. They make deals and contribute to [...]"
---

Lead

The lead variable defines the content of the first paragraph on a page. This is usually an introduction, informing the reader what this page is referring to, what they're about to learn, and any prerequisites for understanding the content on this page. Often, the content of this variable is the same as the description variable.

---
lead: "The Filecoin Network is made with storage providers and clients. They make deals and contribute to [...]"
---

Weight

The weight variable defines where this page or menu item should be in a menu. The lower the number, the closer to the start of the menu this page will be. If set, weight should be non-zero, as 0 is interpreted as an unset weight. There is no upper limit for a weight value.

In the top-bar menu, a lower number will cause the menu item to be further to the left in a regular view or further to the top in a mobile view.

This example is from the /config/_default/menus/menus.en.toml file:

[[main]]
  name = "About Filecoin"
  url = "/about-filecoin/what-is-filecoin"
  weight = 10
  
[[main]]
  name = "Networks"
  url = "/networks/overview"
  weight = 20

[[main]]
  name = "Get started"
  url = "/get-started/overview"
  weight = 30

In the sidebar menu, a lower number will cause the menu item or page to be higher up.

The weight of a page also defines the next and previous buttons at the bottom of the page. The previous page will be the page with the closest weight below the current page's weight. The next page will be the page with the closest weight above the current page's weight.

Menu

The menu variable defines which sidebar menu this page is assigned to, along with which sub-menu this page falls under. This variable is made of three parts:

1. The menu delimiter. This tells Hugo that were are about to define the menu object for this page.
2. The section/top-bar menu that this page falls under.
3. The sub-menu within the sidebar that this page falls under.

---
menu:
    store:
        parent: "store-filecoin-plus"
---

Sidebar menu

Each section has its own sidebar menu. The name of each sidebar menu is usually a lowercase version of the name of the section. For sections that contain a space, the sidebar menu name is a lowercase version of the section without the space:

---
menu:
    storageprovider:
---

Sub-menu

You can think of a sub-menu as the dropdown item in the sidebar menu. Sub-menus are defined in /config/\_default/menus/menus.en.toml. Each sub-menu is a child of a sidebar menu. A sidebar menu can contain multiple sub-menus, but a sub-menu can only belong to one sidebar menu.

Sub-menus are made up of:

• name: The visible text shown to the user.
• weight: How high or low this sub-menu is shown within the sidebar.
• identifier: A unique string used in the front-matter to specify this particular sub-menu.
• url: The default page a user will go to if they click on this sub-menu link.

[[about]]
  name = "Basics"
  weight = 10
  identifier = "about-filecoin-basics"
  url = "/about-filecoin/what-is-filecoin"

...

[[networks]]
  name = "Overview"
  weight = 10
  identifier = "networks-overview"
  url = "/networks/"

...

[[getstarted]]
  name = "Overview"
  weight = 1 
  identifier = "getstarted-overview"
  url = "/get-started/overview/"

To assign a page to a sub-menu, you must supply both the menu object name and the identifier value into the front-matter:

menu:
    getstarted:
        parent: "getstarted-overview"

The identifier of each sub-menu is usually the menu object name and the title of the sub-menu, all in lowercase with dashes -:

Aliases

The aliases variable defines URLs will redirect to this page. Each page can have multiple aliases, but each alias can only appear once throughout all the .md files within the /content folder.

For example, the /get-started/overview page can list /get-started as one of its aliases. However, no other page can list /get-started as an alias. If you attempt to assign another page the /get-started alias, Hugo will throw an error when you or Fleek try to build the website.

Aliases only work for internal links. You cannot assign a redirect to an external website using an alias.

---
aliases:
    - /get-started
    - /how-to/install-filecoin
---

Draft

The draft variable, when set to true, will hide the page from all site navigation. The page will still be accessible by visiting its URL. If this variable is not set, Hugo will assume that it is set to false.

draft: true

This feature is generally used when we need to share content that isn't fully complete, but some users could benefit from its information at this exact moment.

Features

This project contains some handy features you can include within your project.

Archived content

Old pages can be archived and hidden from the sidebar view. However, the can still be accessed for historical purposes.

To archive a page:

1. Move the page and any associated images into the /content/en/archive directory.

2. Add an alias redirect using the original location of this file:

   ---
   ...
   aliases:
       - "/build/tools/filecoin-pinning-services/"
   ---

3. Add the following shortcode to the top of the page, just below the front-matter

   ---
   
   {{< archived-content >}}
   
   ...

Take a look at the /content/en/archive directory for examples.

Tooltips

To make understanding terms in the docs a bit easier, users can hover over certain terms to get a short definition. These descriptions are located within a dict variable at the top of the layouts/shortcodes/tooltip.html shortcode:

<!-- Create array/map of all possible tooltips. -->
{{ $tooltips := dict
    "dApps" "Decentralized applications that don't rely on centralized infrastructure."
    "IPFS" "The InterPlanetary File System (IPFS) is a peer-to-peer protocol for sharing and storing files on the internet, designed to be decentralized and distributed."
    "Lotus" "The reference node implementation for the filecoin network."
    "Lily" "Software designed to simplify the recording of blockchain data."
    "web3" "A new iteration of the World Wide Web which incorporates concepts such as decentralization, blockchain technologies, and token-based economics."
}}

...

Within your markdown you can use one of these tooltips with the following syntax:

[...] storage on {{< tooltip "IPFS" >}} with blockchain-powered [...]

The tooltip should show up once the site has built:

Issues

Found a problem with the Filecoin docs site? Please raise an issue. Be as specific and descriptive as possible; screenshots help!

License

Dual-licensed: MIT, Apache Software License v2, by way of the Permissive License Stack.

Acknowledgments

• Fleek web hosting
• Hugo static site generator
• Doks starter theme