diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index f461e228c..e40ec98cc 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -311,6 +311,7 @@ module.exports = { baseURL: DEPLOY_DOMAIN } ], + 'vuepress-plugin-check-md', 'vuepress-plugin-ipfs' ], extraWatchFiles: ['.vuepress/nav/en.js'] diff --git a/docs/build/README.md b/docs/build/README.md index 93a287424..d9eef62c9 100644 --- a/docs/build/README.md +++ b/docs/build/README.md @@ -26,7 +26,7 @@ Read the resources in the **Start Building** section before you begin for helpfu - [Meme Marketplace](./examples/meme-marketplace/overview/): An example application built on Textile Hub, a Filecoin-backed IPFS Pinning Service. - [Simple Pinning Service](./examples/simple-pinning-service/overview/): An example application built on Powergate. -- [Slate](./examples/filecoin-gui/overview/): A production application built on Powergate. +- [Slate](./examples/slate/overview/): A production application built on Powergate. - [Network Inspector](./examples/network-inspector/overview/): An example application built on lotus. Please suggest any additional content that you would find useful using the links below. diff --git a/docs/build/core-products/protocol-implementations.md b/docs/build/core-products/protocol-implementations.md index 13f93ff5a..8e3c15bc9 100644 --- a/docs/build/core-products/protocol-implementations.md +++ b/docs/build/core-products/protocol-implementations.md @@ -49,7 +49,7 @@ If interacting with the implementation’s RPC APIs, the general development pat Filecoin protocol implementations provide access to core Filecoin protocol workflows, with very few abstractions of the core concepts. This can be very useful, as it allows flexibility and precision in interacting with Filecoin network functionality. However, integrating nodes directly can require greater familiarity with how Filecoin works. To learn more about the various workflows enabled by the core Filecoin protocol, check-out the [How-tos](../../how-to). ::: tip -See a walkthrough of an end-to-end example application (the Filecoin Network Inspector) built using Lotus’ JS API client [here](../../examples/network-inspector/overview). +See a walkthrough of an end-to-end example application (the Filecoin Network Inspector) built using [Lotus’ JS API client](../examples/network-inspector/overview). ::: ## Resources diff --git a/docs/build/examples/sample-architectures.md b/docs/build/examples/sample-architectures.md index dbc3012a1..e0d53cef0 100644 --- a/docs/build/examples/sample-architectures.md +++ b/docs/build/examples/sample-architectures.md @@ -7,8 +7,8 @@ description: Learn how you might build an app on top of Filecoin. No matter what you wish to build on Filecoin, you'll generally need a few basic elements: -- **A node.** Each Filecoin-based service or application will need to use at least one Filecoin node that maintains consensus. All interactions with the network must flow through an up-to-date node: sending and receiving market deals, sending and receiving data, and more. You can host this yourself, or choose a [hosted node](/build/start-building/interacting-with-the-network/) option. -- **An API.** Depending on language, and your preference for more granular or high-level commands, you can either directly use the node's go RPC API, or use one of the available [JS API client libraries](/build/developer-tools/wallets-signing-tools-api-clients/#api-clients). +- **A node.** Each Filecoin-based service or application will need to use at least one Filecoin node that maintains consensus. All interactions with the network must flow through an up-to-date node: sending and receiving market deals, sending and receiving data, and more. You can host this yourself, or choose a [hosted node](../start-building/interacting-with-the-network/) option. +- **An API.** Depending on language, and your preference for more granular or high-level commands, you can either directly use the node's go RPC API, or use one of the available [JS API client libraries](../developer-tools/wallets-signing-tools-api-clients/#api-clients). - Optional: Additional helper tools and libraries to simplify functions such as storage commands, managing deals, and more. ### Examples diff --git a/docs/community/README.md b/docs/community/README.md index ed1a9aa8b..ccdd0ba7b 100644 --- a/docs/community/README.md +++ b/docs/community/README.md @@ -9,7 +9,7 @@ Filecoin is home to a vibrant, diverse community of thousands of contributors an ## Ways to contribute -No matter your area of specialty or level of expertise, there are many [ways to contribute](/community/contribute/ways-to-contribute/) to Filecoin and make a real difference in the Filecoin community at large. +No matter your area of specialty or level of expertise, there are many [ways to contribute](./contribute/ways-to-contribute/) to Filecoin and make a real difference in the Filecoin community at large. ## Filecoin forums diff --git a/docs/community/contribute/contribution-tutorial.md b/docs/community/contribute/contribution-tutorial.md index 851bea85d..dd0acd5f1 100755 --- a/docs/community/contribute/contribution-tutorial.md +++ b/docs/community/contribute/contribution-tutorial.md @@ -5,7 +5,7 @@ description: Contribute to Filecoin documentation by finding issues, fixing them # Contribution tutorial -While the [grammar, formatting, and style](/community/contribute/grammar-formatting-and-style/) and the [writing guide](/community/contribute/writing-guide/) can both help you write excellent content for the Filecoin Docs project, they don't delve into how you can actually submit you content changes. This guide will walk you through finding an issue, fixing it, and then submitting your fix to the `filecoin-project/filecoin-docs` project. +While the [grammar, formatting, and style](./grammar-formatting-and-style) and the [writing guide](./writing-guide) can both help you write excellent content for the Filecoin Docs project, they don't delve into how you can actually submit you content changes. This guide will walk you through finding an issue, fixing it, and then submitting your fix to the `filecoin-project/filecoin-docs` project. There are plenty of small-sized issues around Filecoin documentation that make for easy, helpful contributions to the Filecoin project. Here, we'll walk through: diff --git a/docs/community/contribute/grammar-formatting-and-style.md b/docs/community/contribute/grammar-formatting-and-style.md index 76c17bddc..b0f6768c4 100755 --- a/docs/community/contribute/grammar-formatting-and-style.md +++ b/docs/community/contribute/grammar-formatting-and-style.md @@ -5,7 +5,7 @@ description: Learn the syntax and formatting rules for writing documentation for # Grammar, formatting, and style -This page details the syntax and formatting rules for writing Filecoin documentation. For more conceptual ideas of writing, check out the [writing guide](/community/contribute/writing-guide/). +This page details the syntax and formatting rules for writing Filecoin documentation. For more conceptual ideas of writing, check out the [writing guide](./writing-guide). ## Grammar and spelling diff --git a/docs/community/contribute/ways-to-contribute.md b/docs/community/contribute/ways-to-contribute.md index a565db356..f0ec6b949 100644 --- a/docs/community/contribute/ways-to-contribute.md +++ b/docs/community/contribute/ways-to-contribute.md @@ -30,14 +30,14 @@ Filecoin is a huge project and undertaking, and with lots of code comes the need Before contributing to the Filecoin docs, please read these quick guides; they'll save you time and help keep the docs accurate and consistent! -1. [Style and formatting guide](/community/contribute/grammar-formatting-and-style/) -2. [Writing guide](/community/contribute/writing-guide/) +1. [Style and formatting guide](./grammar-formatting-and-style) +2. [Writing guide](./writing-guide) -If you have never contributed to an open-source project before, or just need a refresher, take a look at the [contribution tutorial](/community/contribute/contribution-tutorial/). +If you have never contributed to an open-source project before, or just need a refresher, take a look at the [contribution tutorial](./contribution-tutorial). ### Community -If interacting with people is your favorite thing to do in this world, join the [Filecoin chat and discussion forums](community/chat-and-discussion-forums/) to say hello, meet others who share your goals, and connect with other members of the community. +If interacting with people is your favorite thing to do in this world, join the [Filecoin chat and discussion forums](../chat-and-discussion-forums) to say hello, meet others who share your goals, and connect with other members of the community. ### Build Applications diff --git a/docs/community/contribute/writing-guide.md b/docs/community/contribute/writing-guide.md index bd6f4ade3..67d4ebba3 100755 --- a/docs/community/contribute/writing-guide.md +++ b/docs/community/contribute/writing-guide.md @@ -5,7 +5,7 @@ description: Learn the specifics of how to write documentation for the Filecoin # Writing guide -This guide explains how to write an article. While the [grammar, formatting, and style guide](/community/contribute/grammar-formatting-and-style/) lets you know the rules you should follow, this guide will help you to properly structure your writing and choose the correct tone for your audience. +This guide explains how to write an article. While the [grammar, formatting, and style guide](./grammar-formatting-and-style) lets you know the rules you should follow, this guide will help you to properly structure your writing and choose the correct tone for your audience. ## Walkthroughs @@ -17,7 +17,7 @@ The vast majority of documentation within the Filecoin Docs project falls under Use the following goals when writing walkthroughs: -| Goal | Keyword | Explanation | +| Goal | Keyword | Explanation | | ------------- | ----------- | ----------------------------------------------------------------- | | **Audience** | _General_ | Easy for anyone to read with minimal effort. | | **Formality** | _Neutral_ | Slang is restricted, but standard casual expressions are allowed. | @@ -53,7 +53,7 @@ These articles are vastly different in tone when compared to walkthroughs. Some Use the following goals when writing conceptual articles: -| Goal | Keyword | Explanation | +| Goal | Keyword | Explanation | | ------------- | ------------------------ | -------------------------------------------------------------------------------- | | **Audience** | _Knowledgeable_ | Requires a certain amount of focus to understand. | | **Formality** | _Neutral_ | Slang is restricted, but standard casual expressions are allowed. | @@ -79,7 +79,7 @@ Take the hypothetical tutorial _Get up and running with Filecoin_, for example. 1. A brief introduction to what Filecoin is. 2. Choose and install a command line client. -3. Understanding storage deals. +3. Understanding storage deals. 4. Import and store a file. Pages `1` and `3` are conceptual articles, describing particular design patterns and ideas to the reader. All the other pages are walkthroughs instructing the user how to perform one specific action. diff --git a/docs/how-to/store/large-files.md b/docs/how-to/store/large-files.md index d8e8141aa..6a5409fd8 100644 --- a/docs/how-to/store/large-files.md +++ b/docs/how-to/store/large-files.md @@ -15,7 +15,7 @@ Filecoin can store any file format, but for very large files we recommend using ### Maximizing storage -The [simple recommendation](<(/how-to/store-prepare-data)>) is that files must be smaller than a sector. Colloquially, we refer to sectors as 1MB, 32GB, etc. To fully maximize storage usage, chunks can be fractionally larger. This is due to a combination of quirks: +The [simple recommendation](./prepare-data) is that files must be smaller than a sector. Colloquially, we refer to sectors as 1MB, 32GB, etc. To fully maximize storage usage, chunks can be fractionally larger. This is due to a combination of quirks: - **Binary size:** Filecoin uses base 2 (binary) sizes. A "1MB sector" is actually 1MiB, or 1,048,576 bytes not 1,000,000 bytes. - **Padding:** For every 256 bits, subtract 2 bits (used by the Proofs processes). The remainder, 254 bits, is the usable storage space. diff --git a/docs/how-to/store/prepare-data.md b/docs/how-to/store/prepare-data.md index 76cf52dbf..16aaa9ad4 100644 --- a/docs/how-to/store/prepare-data.md +++ b/docs/how-to/store/prepare-data.md @@ -25,4 +25,4 @@ Block data structures must be serialized into flat string files before importing For simple operations, you can use the `split` or `zip` Unix commands. Or, choose a client application that handles data preparation for you, such as the [Starling Storage CLI & REST API](https://github.com/filecoin-project/starling). -Note: See [Very Large Files](/how-to/store-large-files) if you plan to store files larger than 1TB. +Note: See [Very Large Files](./large-files) if you plan to store files larger than 1TB. diff --git a/docs/mine/mining.md b/docs/mine/mining.md index 7c802b7eb..b3aa5eccf 100644 --- a/docs/mine/mining.md +++ b/docs/mine/mining.md @@ -13,9 +13,9 @@ Mining in Filecoin works quite differently however -- instead of contributing co The Filecoin network will have multiple types of miners: -* Storage miners, responsible for storing files and data on the network. -* Retrieval miners, responsible for providing quick pipes to retrieve files. -* Repair miners, which are to be implemented. +- Storage miners, responsible for storing files and data on the network. +- Retrieval miners, responsible for providing quick pipes to retrieve files. +- Repair miners, which are to be implemented. **Storage miners** are the heart of the network. They earn Filecoin by storing data for clients, and computing cryptographic proofs to verify storage across time. The probability of earning the block reward and transaction fees is proportional to the amount of storage the miner contributes to the Filecoin network, and not hashing power. @@ -27,10 +27,10 @@ In the current implementation, the focus is mostly on storage miners, which sell The current recommended system specifications for operating a storage miner are: -* An 8+ core CPU -* A NVIDIA-manufactured GPU chip (to be expanded on) -* A dedicated SSD to act as a large cache store (512GB+) -* A large amount of RAM for computing data replication (128GB+) +- An 8+ core CPU +- A NVIDIA-manufactured GPU chip (to be expanded on) +- A dedicated SSD to act as a large cache store (512GB+) +- A large amount of RAM for computing data replication (128GB+) ## Getting started as a miner @@ -58,9 +58,9 @@ In Filecoin, miners are succeptible to two different kinds of slashing: **storag **Storage fault slashing** is a term that is used to encompass a broader set of penalties, including (but not limited to) fault fees, sector penalties and termination fees. These penalties are to be paid by miners if they fail to provide sector reliability or decide to voluntarily exit the network. -* A **fault fee** is a penalty that a miner incurs for each day a miner’s sector is offline. -* A **sector penalty:** is a penalty that a miner incurs for a faulted sector that was not declared faulted before a [WindowPoSt check](#window-post-checks) occurs. - * The sector will pay a Fault Fee after a Sector Penalty once the fault is detected -* A **termination fee:** is a penalty that a miner incurs when a sector is voluntarily or involuntarily terminated and is removed from the network. +- A **fault fee** is a penalty that a miner incurs for each day a miner’s sector is offline. +- A **sector penalty:** is a penalty that a miner incurs for a faulted sector that was not declared faulted before a `WindowPoSt` check occurs. + - The sector will pay a Fault Fee after a Sector Penalty once the fault is detected +- A **termination fee:** is a penalty that a miner incurs when a sector is voluntarily or involuntarily terminated and is removed from the network. **Consensus fault slashing** is the penalty that a miner incurs for committing consensus faults. This penalty is applied to miners that have acted maliciously against the network’s consensus functionality. diff --git a/docs/project/README.md b/docs/project/README.md index 5154cc90d..43e9021d4 100644 --- a/docs/project/README.md +++ b/docs/project/README.md @@ -2,6 +2,7 @@ title: The Filecoin Project description: Learn about the history, roadmap, current status and more for Filecoin --- + # The Filecoin Project Curious about how it all got started, or where we're headed? Learn about the history, current state, and future trajectory of the Filecoin project here. @@ -16,7 +17,7 @@ Learn about the ongoing cryptography research and design efforts that underpin t ## Related projects -Filecoin is a highly modular project that is itself made out of many different protocols and tools. Learn more about the [Filecoin-related projects](/project/related-projects/) supported by Protocol Labs. +Filecoin is a highly modular project that is itself made out of many different protocols and tools. Learn more about the [Filecoin-related projects](related-projects) supported by Protocol Labs. ## Code of conduct diff --git a/package-lock.json b/package-lock.json index 4f25e6455..aeb6b8274 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1059,6 +1059,16 @@ "integrity": "sha512-9NET910DNaIPngYnLLPeg+Ogzqsi9uM4mSboU5y6p8S5DzMTVEsJZrawi+BoDNUVBa2DhJqQYUFvMDfgU062LQ==", "dev": true }, + "@sindresorhus/slugify": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/slugify/-/slugify-0.8.0.tgz", + "integrity": "sha512-Y+C3aG0JHmi4nCfixHgq0iAtqWCjMCliWghf6fXbemRKSGzpcrHdYxGZGDt8MeFg+gH7ounfMbz6WogqKCWvDg==", + "dev": true, + "requires": { + "escape-string-regexp": "^1.0.5", + "lodash.deburr": "^4.1.0" + } + }, "@szmarczak/http-timer": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/@szmarczak/http-timer/-/http-timer-1.1.2.tgz", @@ -3040,6 +3050,27 @@ "integrity": "sha512-3Xnr+7ZFS1uxeiUDvV02wQ+QDbc55o97tIV5zHScSPJpcLm/r0DFPcoY3tYRp+VZukxuMeKgXYmsXQHO05zQeA==", "dev": true }, + "check-md": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/check-md/-/check-md-1.0.0.tgz", + "integrity": "sha512-H9LS+TDB6ix4QZQFiTp2TVIL+24zKutOKDqxIxAxnvkx3phpzrwPINaykD8RSeynxIVp3s0PecR2GEA3KLbziQ==", + "dev": true, + "requires": { + "@sindresorhus/slugify": "^0.8.0", + "chalk": "^2.4.2", + "commander": "^2.19.0", + "diacritics": "^1.3.0", + "globby": "^9.1.0" + }, + "dependencies": { + "commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "dev": true + } + } + }, "chokidar": { "version": "3.0.2", "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.0.2.tgz", @@ -7518,6 +7549,12 @@ "integrity": "sha1-gteb/zCmfEAF/9XiUVMArZyk168=", "dev": true }, + "lodash.deburr": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/lodash.deburr/-/lodash.deburr-4.1.0.tgz", + "integrity": "sha1-3bG7s+8HRYwBd7oH3hRCLLAz/5s=", + "dev": true + }, "lodash.defaults": { "version": "4.2.0", "resolved": "https://registry.npmjs.org/lodash.defaults/-/lodash.defaults-4.2.0.tgz", @@ -12696,6 +12733,15 @@ "integrity": "sha512-R2mcc+bp9VbKBQ3YIbCqUbWcWfmWSp1NIEyNGiLKkrcZmyUF/+0D48BqMCTx61AgJzWPW5DJzB6VkmpjbMIDbA==", "dev": true }, + "vuepress-plugin-check-md": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/vuepress-plugin-check-md/-/vuepress-plugin-check-md-0.0.2.tgz", + "integrity": "sha512-XwA/IiMNvR42L3ajmkr+6JY3JRnhDN+uluh1wLYl0VAI8VqTkXT7Ng4xlxgebfLPChEFPnJgcydGv8E52Zdpig==", + "dev": true, + "requires": { + "check-md": "1.0.0" + } + }, "vuepress-plugin-clean-urls": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/vuepress-plugin-clean-urls/-/vuepress-plugin-clean-urls-1.1.1.tgz", diff --git a/package.json b/package.json index d1cbc4413..2b7859adb 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,7 @@ "stylus-supremacy": "^2.14.5", "vuepress": "^1.5.2", "vuepress-plugin-canonical": "^1.0.0", + "vuepress-plugin-check-md": "0.0.2", "vuepress-plugin-clean-urls": "^1.1.1", "vuepress-plugin-ipfs": "^1.0.2", "vuepress-plugin-robots": "^1.0.1", @@ -49,7 +50,8 @@ }, "husky": { "hooks": { - "pre-commit": "lint-staged" + "pre-commit": "lint-staged", + "pre-push": "npm run docs:links" } }, "scripts": { @@ -57,6 +59,7 @@ "test": "echo \"Error: no test specified\" && exit 1", "format:styles": "stylus-supremacy format ./docs/.vuepress/**/*.styl --replace", "docs:dev": "vuepress dev docs", - "docs:build": "vuepress build docs" + "docs:build": "npm run docs:links && vuepress build docs", + "docs:links": "vuepress check-md docs" } }