• Stars
    star
    220
  • Rank 180,422 (Top 4 %)
  • Language
    Shell
  • Created over 4 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Filecoin Docs

Contributors Forks Issues [MIT License][license-url] Website status


The Filecoin project logo.

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

Table of contents

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

    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
  1. Visit localhost:1313 to view the site.
  2. 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

The Filecoin project logo.

This repository manages the documentation for the Filecoin project. This repository 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.

Merge process

This project receives a lot of pull requests from many individual contributors. Because of this, the Filecoin Docs team merges any new changes into production on Wednesdays only. Any commits or PRs into this repo on any other day will land in the staging branch. This process has several benefits:

  • Reviewing and editing content is more manageable.
  • Mass formatting, spelling, and grammar changes can happen on a single branch.
  • Breaking changes are much less likely.

Only issues and PRs tagged as p0 will be merged directly into production outside the Wednesday merge window. Take a look at the Priority section for information on how we tag issues.

Files and folders

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

Name Purpose
.git, .github Manage the git configurations and contain information for GitHub constant integrations.
README.md This file. Acts as an introduction to this repository and how to spin up a local copy of the docs.filecoin.io site.
archetypes/ Used by Hugo to programmatically create new pages.
assets/ Assets like JavaScript and fonts used by Hugo to create the static site. These assets are not explorable in a built site. You must reference them in the code before building the site.
babel.config.js A configuration file used for the Babel JS compiler.
config/ Contains the configuration files for Hugo. You can manage things like the top-bar menu and site title within this directory.
content/ This is where all the .md files live that control the content of this site. Most contributions happen in this directory.
data/ You can supply extra variables for Hugo to use when building pages in this directory. These variables act just like front-matter variables. See Data Templates in the Hugo docs for more info.
functions/ Functions callable from any template, partial, or shortcode within Hugo.
i18n/ Contains files specific to managing different languages.
layouts/ This is where web developers will likely spend most of their time. This folder contains the shortcodes and partials that Hugo uses to scaffold and build the site.
node_modules/ Where NPM throws its packages. If you see this in GitHub, something's gone wrong. It should only exist on your computer after you run npm install.
package-lock.json One of the NPM configuration files. Specify which version of packages to download.
package.json Another one of the NPM configuration files. Specifies which packages to download but doesn't specify which version of the package to grab.
resources/ A cache where Hugo throws generated files like CSS and JSON after npm run build has been called. Unless npm run clean is called, Hugo will re-use these files when calling npm run build.
static/ Images, CSS, fonts, and other misc files that are available at docs.filecoin.io/ when the site is built. For example, docs.filecoin.io/site.webmanifest.
theme.toml A Hugo configuration file that specifies which theme to use. This file should not change that often.

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.

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

Section Sidebar menu name
Basics basics
Store store
Storage providers providers
Nodes nodes
Smart contracts smart-contracts
Networks networks
Reference reference
menu:
  smart-contracts:
    parent: "smart-contracts-fundamentals"
    identifier: "overview-3c010e7c403589b274c1d6d9dd0311c5"
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.
[[main]]
  name = "Smart Contracts"
  url = "/smart-contracts/fundamentals/the-filecoin-virtual-machine/"
  weight = 40
  identifier= "main-smart-contracts"

    [[main]]
      name = "Fundamentals"
      url = "/smart-contracts/fundamentals/the-filecoin-virtual-machine/"
      weight = 10
      parent = "main-smart-contracts"

    [[main]]
      name = "Filecoin EVM runtime"
      url = "/smart-contracts/filecoin-evm-runtime/actor-types/"
      weight = 20
      parent = "main-smart-contracts"

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

Pre-commit linters

This feature is currently in beta. If you believe that the pre-commit step incorrectly flagged something that it shouldn't have, or you just need help with the linters, please reach out to the docs team directly so we may assist you. For the fastest response, find us in the public #pl-docs channel.

Before local changes can be committed to filecoin-docs, a custom shell script to check Markdown file quality using NPM packages is run. To use the pre-commit linters, follow the steps described below:

  1. In a local copy of the repository, make changes to one or more more Markdown files.

  2. Stage the changes:

    git add .
  3. Commit the staged changes locally with a short and useful message describing the commit <commit-msg>:

    git commit -m "<commit-msg>"
  4. The pre-commit step is triggered, where the following open-source linters are run against all locally committed files, as described below:

    Linter Usage Command used Configuration
    markdown-spellcheck Flag misspelled words, improper terminology mdspell -r -a -n --en-us .spelling
    markdownlint-cli2 Flag improperly formatted markdown markdownlint-cli2 .markdownlint-cli2.jsonc
    markdown-link-check Flag broken URLs markdown-link-check --config .mdlinkcheck-config.json -q -p .mdlinkcheck-config.json

    The script combines the output of these linters, and does one of the following:

    • Fails and rejects the commit if any issues are flagged, and reports those issues to the user:
      • Spelling
      • Markdown formatting
      • Broken links
    • Succeeds and accepts the commit if no markdown files were changed or no errors were found.

Before you can commit to the repository, you must fix any errors identified. To do so, follow the steps below:

Fix broken links
  1. Fix any improperly formatted links.
  2. Remove or replace any links that are returning a 404.
Fix markdown formatting
  1. Open a terminal window in the root directory of filecoin-docs and run format-fix.sh:

    sh format-fix.sh

    The following occurs:

    • The script attempts to auto-fix identified errors. Only certain errors are automatically fixable, so this will not usually catch everything.
    • A summary of any remaining errors that the script could not automatically fix is displayed.
  2. Fix the remaining Markdown formatting errors.

Fix spelling mistakes

Open a terminal window in the root directory of filecoin-docs and run spell-fix.sh:

sh spell-fix.sh

The following occurs:

  • A summary of all spelling errors found in the changed file is displayed.
  • Interactive spelling fix mode starts.

Using interactive spelling mode, you can quickly address each spelling error (highlighted in red) by doing the following:

  1. Using the arrow keys, select one of the following options:
    • Ignore will ignore the word and not ask about it again in the current run. If spell check is run again, it will be flagged.
    • Add to file ignores will ignore the word in this file only.
    • Add to dictionary - case insensitive will add to the dictionary for all files and match any case. Because this option updates the repository dictionary, the docs team will require further review.
    • Add to dictionary - case sensitive will add to the dictionary for all files and match the case that has been used. Because this option updates the repository dictionary, the docs team will require further review.
    • Enter correct spelling will allow you to manually enter the correct spelling.
    • Any of the suggested fixes that the tool lists below Enter correct spelling.
  2. Once you've selected an option, press the Enter key.
  3. Repeat steps 2 and 3 until no more errors remain.

Archived content

Old pages can be archived and hidden from the sidebar view. However, they 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.

Code tabs

We can use code tabs to split a section or instruction into different parts based on programming language, operating system, or something else.

The following code creates three code tabs called JavaScript, Go, and Rust:

{{< tabs tabTotal="3">}}
{{< tab tabName="JavaScript" >}}

<pre>
function main() {
    console.log("Hello world");
}
</pre>

{{< /tab >}}
{{< tab tabName="Go" >}}

<pre>
package main
import "fmt"

func main() {
    fmt.Println("Hello world")
}
</pre>


{{< /tab >}}
{{< tab tabName="Rust">}}

<pre>
fn main() {
    println!("Hello World");
}
</pre>

{{< /tab >}}
{{< /tabs >}}

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 an 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 been built:

Issues

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

Priority

We use p tags to define the priority of an issue. The priority is defined by the docs team using the following definitions:

Label Impact Due date Example
P0 Severely business-impacting Same day. Drop everything and fix it immediately. The website is down.
P1 Business-impacting. Within three days. The API endpoint for a project is about to change.
P2 Planned project request. Within two weeks. A new method will soon be added to a project API.
P3 Suggestion or conceptual update. No due date. A blog post discussing the benefits of decentralization for web developers.
P4 Deprioritized suggestions. These will not be addressed unless significant activity or community requests are received. No due date. Add a dark theme to the docs.

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

More Repositories

1

lotus

Reference implementation of the Filecoin protocol, written in Go
Go
2,839
star
2

venus

Filecoin Full Node Implementation in Go
Go
2,057
star
3

slate

WIP - We're building the place you go to discover, share, and sell files on the web.
JavaScript
526
star
4

rust-fil-proofs

Proofs for Filecoin in Rust
Rust
490
star
5

community

Filecoin community and ecosystem channels, discussion forums, and more
478
star
6

community-china

Resources and forum for the Chinese community, maintained and moderated by CoinSummer & PL.
C
437
star
7

ref-fvm

Reference implementation of the Filecoin Virtual Machine
Rust
378
star
8

devgrants

๐Ÿ‘Ÿ Apply for a Filecoin devgrant. Help build the Filecoin ecosystem!
375
star
9

specs

The Filecoin protocol specification
SCSS
367
star
10

FIPs

The Filecoin Improvement Proposal repository
Jupyter Notebook
288
star
11

fevm-hardhat-kit

A starter hardhat project for developing, deploying, and testing Solidity smart contracts on the FEVM (Ethereum Virtual Machine on Filecoin)
Solidity
186
star
12

fvm-specs

home of the FVM (Filecoin Virtual Machine) project โš™๏ธ
168
star
13

cpp-filecoin

C++17 implementation of Filecoin
C++
126
star
14

neptune

Rust Poseidon implementation.
Rust
125
star
15

notary-governance

114
star
16

filecoin-plus-large-datasets

Hub for client applications for DataCap at a large scale
110
star
17

boost

Boost is a tool for Filecoin storage providers to manage data storage and retrievals on Filecoin.
Go
110
star
18

lassie

A minimal universal retrieval client library for IPFS and Filecoin
Go
109
star
19

filecoin-ffi

C and CGO bindings for Filecoin's Rust libraries
Rust
94
star
20

specs-actors

DEPRECATED Specification of builtin actors, in the form of executable code.
Go
86
star
21

filecoin-plus-client-onboarding

79
star
22

builtin-actors

The Filecoin built-in actors
Rust
78
star
23

go-fil-markets

Shared Implementation of Storage and Retrieval Markets for Filecoin Node Implementations
Go
78
star
24

research

Home for Filecoin Research
74
star
25

go-jsonrpc

Low Boilerplate JSON-RPC 2.0 library
Go
74
star
26

bls-signatures

BLS Signatures in Rust
Rust
74
star
27

ec-gpu

OpenCL code generator for finite-field arithmetic over arbitrary prime fields
Rust
69
star
28

rust-gpu-tools

Rust tools for OpenCL and GPU management.
Rust
66
star
29

replication-game

Compete on the fastest replication algorithm
Rust
59
star
30

slingshot

Official repository for Filecoin's Space Race 2: Slingshot
58
star
31

filecoin

GitHub home for the Filecoin Project
52
star
32

starling

Demo storage client for archival video data
JavaScript
51
star
33

lily

capturing on-chain state for the filecoin network
Go
49
star
34

venus-docs

Content for Venus tutorial
Shell
49
star
35

rust-filecoin-proofs-api

Rust
43
star
36

consensus

Filecoin consensus work
Python
42
star
37

blstrs

Rust
40
star
38

mir

Go
40
star
39

go-data-transfer

Data Transfer Shared Component for go-filecoin & go-lotus
Go
39
star
40

dagstore

a sharded store to hold large IPLD graphs efficiently, packaged as location-transparent attachable CAR files, with mechanical sympathy
Go
39
star
41

storetheindex

A storethehash based directory of CIDs
Go
36
star
42

fvm-starter-kit-deal-making

Full dapp starter kit for automating Filecoin deal making
JavaScript
36
star
43

go-statemachine

Go
34
star
44

dealbot

๐Ÿค–๐Ÿค A bot for making deals
Go
32
star
45

benchmarks

A place for community-submitted Filecoin benchmarks
JavaScript
32
star
46

core-devs

Technical Project Management: Meeting notes and agenda items
32
star
47

lotus-docs

Documentation for Lotus
HTML
29
star
48

fevm-data-dao-kit

A kit to demonstrate the basics of getting a DataDAO up and running on the Filecoin Virtual Machine (FVM).
JavaScript
29
star
49

go-hamt-ipld

An implementation of a HAMT using ipld
Go
28
star
50

sentinel

Filecoin Network monitoring and analysis tools.
27
star
51

filecoin-explorer

Filecoin block explorer
JavaScript
26
star
52

motion

๐Ÿ๏ธ Accelerating Data onto FileCoin
Go
25
star
53

rust-fil-nse-gpu

Rust interface to GPU implementation of Filecoin's Narrow Stacked Expander (NSE) sealing algorithm
Rust
24
star
54

testnet-hyperspace

Meta info about the developer-focused Hyperspace testnet for Filecoin developers
24
star
55

sector-storage

A concrete implementation of the specs-storage interface
Go
24
star
56

fevm-foundry-kit

A starter foundry project for developing, deploying, and testing Solidity smart contracts on the FEVM (Ethereum Virtual Machine on Filecoin)
Solidity
23
star
57

testnet-wallaby

Meta info about the Wallaby testnet for FVM developers
20
star
58

go-legs

Does the legwork for go-data-transfer
Go
20
star
59

filecoin-client-tutorial

Store data on the Filecoin Network in under 5 minutes.
JavaScript
20
star
60

go-leb128

LEB128 integer encoding
Go
20
star
61

awesome-filecoin

Curated list of useful resources for Filecoin
19
star
62

venus-wallet

a remote wallet for provider sign service
Go
19
star
63

eudico

lotus, but also other things
Go
19
star
64

go-state-types

Primitive and low level types used in chain state and actor method parameters
Go
19
star
65

designdocs

Docs that capture the design intent for important components
18
star
66

neptune-triton

Futhark implementation of neptune-compatible Poseidon.
C
18
star
67

orient

โ†ปObserve-Orient-Decide-Actโ†ฉ
Common Lisp
18
star
68

test-vectors

๐Ÿ’Ž VM and Chain test vectors for Filecoin implementations
Go
18
star
69

filecoin-solidity

Filecoin Solidity API Library
Solidity
17
star
70

filsnap

MetaMask snap for interacting with Filecoin dapps.
TypeScript
17
star
71

go-address

Go
17
star
72

venus-sealer

Go
17
star
73

data-prep-tools

Python
17
star
74

fvm-evm

EVM runtime for the Filecoin Virtual Machine
Rust
15
star
75

actors-utils

Collection of libraries to implement common patterns and standards on the Filecoin Virtual Machine
Rust
15
star
76

filecoin-network-viz

Filecoin Network Visualization Frontend
JavaScript
14
star
77

rust-fil-sector-builder

Rust
13
star
78

filecoin-fvm-localnet

A complete filecoin lotus and boost docker image to spin up a localnet for smart contract development
Shell
13
star
79

fvm-docs

Documentation and website build scripts for the Filecoin Virtual Machine (FVM) project.
HTML
12
star
80

chain-validation

(DEPRECATED) See https://github.com/filecoin-project/test-vectors instead. (was: chain validation tools)
Go
11
star
81

fvm-runtime-experiment

Rust
11
star
82

fungi

A distributed task runner
Go
11
star
83

go-dagaggregator-unixfs

Go
10
star
84

go-fil-commp-hashhash

A hash.Hash implementation of fil-commitment-unsealed
Go
10
star
85

lua-filecoin

Prototype of Filecoin in Lua
Lua
10
star
86

statediff

State Inspector ๐Ÿ•ต๏ธโ€
Go
10
star
87

go-amt-ipld

Implementation of an array mapped trie using go and ipld
Go
9
star
88

fil-blst

Assembly
9
star
89

go-sectorbuilder

Go
8
star
90

sp-automation

Jinja
8
star
91

go-f3

Golang implementation of Fast Finality in Filecoin (F3)
Go
8
star
92

oni

๐Ÿ‘น (DEPRECATED; see README) Project Oni | Network Validation
Go
7
star
93

helm-charts

Smarty
7
star
94

boost-docs

Documentation for Boost
7
star
95

slate-react-system

A component, constants, and experience library for the Filecoin Network / Textile Services
7
star
96

go-storage-miner

A Filecoin storage miner
Go
7
star
97

system-test-matrix

The Filecoin System Test Matrix is a dashboard with a detailed list of Filecoin features and behaviors and a mapping between those features and test suites, systems and subsystems that those features are related to.
TypeScript
7
star
98

go-data-segment

Go
6
star
99

raas-starter-kit

JavaScript
6
star
100

fvm-example-actors

A collection of actors, created and maintained by the FVM community.
Solidity
6
star