vjandrea / trufflesuite.com

Trufflesuite website source ✨

New trufflesuite.com

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 web3 constructs
• Improve the CD pipeline

Note that this is first iteration of this initiative and there may be a few 🐉's

Local Setup

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

By default the site will be served over port 8000.

Dependencies Reference

Client-side

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.

• Bootstrap 5.x
• Font Awesome
• Github Buttons

Plugins & Libraries

The following MkDocs plugins are used by the site...

• mkdocs-material
• mkdocs-awesome-pages-plugin
• mkdocs-macros-plugin

In addition, the requests library is used during the site build process.

• requests

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)

Upcoming

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.