README
Filecoin Specification
This is the Filecoin Specification, a repository that contains documents, code, models, and diagrams that constitute the specification of the Filecoin Protocol. This repository is the singular source of truth for the Filecoin Protocol. All implementations of the Filecoin Protocol should match and comply with the descriptions, interfaces, code, and models defined in this specification.
Note that the beta
branch of the specs moves quickly. We work to merge PRs as fast as possible into master, which means changes or reversals are possible here. Accordingly, we periodically compile swaths of spec along with a high-level difflog into the release
branch. As the spec stabilizes, this practice will change.
Website
https://beta.spec.filecoin.io is the user-friendly website rendering, which we recommend for reading this repository. The website is updated automatically with every merge to beta
.
Previous version
You can find the previous version of the Filecoin Spec in the master branch here.
Install
Develop
You need to have Go and bzr
installed (required to build lotus)
Serve with Live Reload
Check your markdown
We have a markdown linter set up to check for common errors like incorrectly nested headers. It runs in CI and you can run it locally with:
Solving Common problems
Problem - Site fails to build with an error that states it faled to download modules on macos
Solution - run npm run clean
- the cache dir hugo uses can get corrupted, and this resets it. See #1048
External modules
External modules should be added as Hugo Modules You can find examples in the config.toml
target
should ALWAYS use the foldercontent/externals
This makes files from external repos available for Hugo rendering and allows for linking to up-to-date files that are directly pulled from other repositories.
The configuration above gives the following information:
path
: Repository's URL without protocol.source
: Folder from the repository referenced in thepath
to be mounted into the local Hugo filesystem.target
: Folder wheresource
will be mounted locally, this should follow this structurecontent/modules/<target value>
.
Example: if you want to link/embed to the file xyz.go
that lives in https://github.com/filecoin-project/specs-actors/actors/xyz-folder/xyz.go
, from within a markdown file then with the above configuration the src
for shortcodes or markdown image syntax would be:
The first foward slash is important it means the path is relative to the content folder.
These modules can be updated with
or to a specific version with
Page Header
The first heading should be an atx style heading # Head
and should refer to the overall title of the document.
Frontmatter
Description for all the available frontmatter properties
Code fences
Code fences should always have a lang, if you don't know or don't care just use text
Images, diagrams - Markdown images
To add an image or diagram you just need to use normal markdown syntax. For diagrams you can use the source files and the pipelines will handle converting that to svg
, we support mermaid and dot source files.
When there's no title we use the alt text as title
References - Markdown links
These links use "portable links" just like relref
so you can just give it the name of the file and it will fetch the correct relative link and title for the <a href="/relative/path" title="page title">
automatically. You can override the <a>
title by passing a second string
in the link definition.
Note: When using anchors the title can't be fetched automatically.
```md
hint
hint
embed
embed
Math mode
For short snippets of math text you can just use the {{<katex>}}
shortcode, but if you need to write lots of math in a page you can just use math-mode
and avoid writting the katex shortcode everywhere.
Parses math typesetting with KaTeX
Check this example example
Some syntax like
\_
can't go through HUGO markdown parser and for that reason we need to wrap math text with code blocks, code fendes or the shortcode{{<plain>}}
. See examples below.
Addmath-mode
prop to the Frontmatter
Wrap def
, gdef
, etc.
def
, gdef
, etc.Math text needs to be wrapped to avoid Hugo's Markdown parser. When wrapping defs or any math block that doesn't need to be rendered the recommended option is to use the shortcode {{<plain hidden}}
with the hidden argument.
Wrap inline math text with code blocks
Wrap math blocks with code fences
References
Last updated