Website
Project overview for WebAssembly: webassembly.org
Dependencies
- Ruby >= 2.3.0
- Bundler
Building the site
Clone the project and the design submodule:
$ git clone https://github.com/WebAssembly/website
$ git submodule update --init --recursive
Install gem dependencies:
$ bundle install
Build with Jekyll or serve local preview:
$ bundle exec jekyll build
$ bundle exec jekyll serve
You must run
bundle exec jekyll buildafter every change and include thedocsdirectory in your commit!
Publishing
This site uses Jekyll plugins, so GitHub Pages will not build it automatically. To publish, check in manually built static site files to the docs directory.
The static site should be configured to build to the docs directory. The docs directory is a special directory from which GitHub pages can publish directly. The naming convention is unfortunate given the confusing overlap with the site's own docs pages (output to docs/docs) which are themselves generated from the design docs submodule located at design.
What is the role of _config.yml and the custom Jekyll plugins?
Note: the following plugins are all hacks to make the workflow of generating website docs from the
designrepo work without updating the sources in the design repo.
gem 'jekyll-optional-front-matter'loaded directly in theGemfileallows markdown files without YAML frontmatter to be consumed directly. This is included to allowdesignrepo.mdfiles to be used as pages without modifying their source to add frontmatter.gem 'jemoji'loaded directly in theGemfilereplaces GitHub-style emoji markdown (e.g.:+1:) with images for compat.- The
defaultssection of_config.ymladds default values to the YAML frontmatter of documents from thedesignrepo. In particular, it specifies that all.mdfiles in the design submodule should be labelled as typedocand given layoutdoc.html. It also manually moves a few docs into thecommunitytree where they fit the site organization better. auto_titles.rbadds atitlevalue to YAML frontmatter by looking for the first header tag in the source files. It also orders the design docs based on a hardcoded list.link_converter.rbturns thedesignrepo's links (e.g.[threads](FutureFeatures.md#threads)) into their respective locations on this website (e.g.[threads](/docs/future-features/#threads)).underscore_paths.rbrewrites Jekyll page permalinks to convert/design/FutureFeatures/to/docs/future-features/.