Project overview for WebAssembly: webassembly.org
- Ruby >= 2.0.0
Building the site
Clone the project and the
$ 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 the
docsdirectory in your commit!
This site uses Jekyll plugins, so GitHub Pages will not build it automatically. To publish, check in manually built static site files to the
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
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 the
Gemfileallows markdown files without YAML frontmatter to be consumed directly. This is included to allow
.mdfiles to be used as pages without modifying their source to add frontmatter.
_config.ymladds default values to the YAML frontmatter of documents from the
designrepo. In particular, it specifies that all
.mdfiles in the design submodule should be labelled as type
docand given layout
doc.html. It also manually moves a few docs into the
communitytree where they fit the site organization better.
titlevalue 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.
.mdemoji signifiers of the form
:unicorn:and emoji unicode characters with image elements which are more accessible.
kramdownMarkdown converter to obey GitHub Flavored Markdown's conventions in generating HTML
idattributes from the contents of headers.
designrepo's links (e.g.
[threads](FutureFeatures.md#threads)) into their respective locations on this website (e.g.
underscore_paths.rbrewrites Jekyll page permalinks to convert