A new version (as of Q4 2021) of the trufflesuite.com site, built upon mkdocs and the material theme.
The goals of this release have included the following:
- Switch to better maintained static site generator (SSG) with a more robust plugin ecosystem
- Update, and if possible remove, some of the heavier client-side dependencies
- Offer a reasonable mobile experience
- Store the site decentrally (on IPFS) and lean into more
- Improve the CD pipeline
Note that this is first iteration of this initiative and there may be a few
First up, you'll need to ensure you have Python
3.8.9 or above installed locally. You can check your current version by running
python3 --version in your terminal. You can download the latest build here or install via brew or equivalent.
Once python3 is setup you'll need to install project dependencies.
pip3 install -r requirements.txt
Assuming the above installed successfully, you can check the globally installed dependencies with
pip3 list. Additionally, MkDocs documentation can be found here.
Running the Site
You can run the site locally with the following...
LOCAL_BUILD=true mkdocs serve
On Windows you may have to run as follows:
$env:LOCAL_BUILD = "true" python3 -m mkdocs serve
LOCAL_BUILD to true will limit the number of boxes generated to 6 boxes. To generate more boxes you'll need to add valid
TRUFFLESUITE_COM_GH_API_KEY values to your environment and then omit the
By default the site will be served over port 8000.
At the time of writing we've removed all custom JS other than that provided by mkdocs-material itself and the following libraries and utilities.
Plugins & Libraries
The following MkDocs plugins are used by the site...
In addition, the
requests library is used during the site build process.
Truffle Box Templating
The site utilizes the Jinja templating engine for building the Truffle Box READMEs. Specifically, during the build process the box's READMEs are pulled from Github's API and stored locally before being passed through the markdown renderer.
response = requests.get("https://api.github.com/repos/" + box['userOrg'] + "/" + box['repoName'] + "/readme", auth=HTTPBasicAuth('...', '...')) json_response = response.json()
As a result, an extra rebuild step is required given these aren't rendered on the first pass.
if not conf['extra']['rebuild']: conf['extra']['rebuild'] = True mkdocs.commands.build.build(conf)
Note that this list will imminently be moved to Github Issues...
- remove the second build step (as above)
- localization - https://github.com/ultrabug/mkdocs-static-i18n
- further optimizations
- troubleshoot ipfs performance issues
Connect or Contribute
As always, we greatly value contributions of all shapes and sizes. Feel free to open an issue, create a pull request or get in touch.