Skip to content

Latest commit

 

History

History
133 lines (101 loc) · 4.58 KB

CONTRIBUTING.md

File metadata and controls

133 lines (101 loc) · 4.58 KB

This website is currently built using GitHub Pages which itself relies on Jekyll. This automatically transforms the content of this repository into a static website hosted on GitHub. We now have a temporary domain pointing to it.

Documentation format

Documentation should be written using Markdown. It will be transformed into HTML during the build process.

To ease online review, lines should be no longer than 80 characters. This is greatly simplified by using reference style links placed at the bottom of the page. For example (lifted off John Gruber's Markdown Syntax guide):

This is [an example][eg] reference-style link.

[...]

Then, anywhere in the document (usually at the end), you define your link
label like this, on a line by itself:

[eg]: http://example.com/

Favor named referenced over indexed ones, as those make refactoring much simpler.

As an added benefit, this syntax makes keeping links up to date a lot easier as they are all placed together at the bottom of the page.

Event page format

Event pages should be written in HTML. A lot of the content is automatically generated from data placed in the YAML front-matter. This includes:

  • name of the venue (venue, and localized_venue fields),
  • date of the event (date, and localized_date fields),
  • title of the page (optional title field),
  • list of event sponsors (sponsors field),
  • list of event speakers (speakers field), and
  • list of event experts (experts field).

Setting the language of the page (lang field) can help automatically localize some of the above.

There are good examples of how to author this YAML front-matter in the page for the Seattle event.

The sponsors, speakers and experts field simply pull data out of the site-wide config file (a poor man's db) which they run through templates to produce markup. So for example:

---
lang: zho
speakers: [Rebecca Hauck]
---

will automatically create the following HTML markup:

<div class="block-speakers">
  <h2 id="speakers" class="hed">专家</h2>
  <ul>
    <li>
      <img width="48" height="48" src="/assets/experts/rhauck.jpg" alt=''>
       <h4>Rebecca Hauck</h4>
       <p>Adobe, CSS Working Group</p>
    </li>
  </ul>
</div>

Note that while sponsors get automatically added to the end of the events page, speakers and experts need to be included via an include tag at the desired location. E.g.:

<p>Some content goes here:</p>

{% include speakers.html %}

<p>All talks will be given in English.</p>

{% include experts.html %}

Should you need to modify or add a speaker, expert or sponsor, please do so in the config file. The format is YAML of which JSON is a subset. Note that speakers and experts share the same experts entry.

File names

File names should be lowercased, hyphenated and use the .md extension, e.g.: review-process.md. The build step will change that to review-process.html and use it as URL.

Contribution workflow

Contributions should follow the standard open source GitHub workflow (fork the repository, work off topic-branches, send atomic commits as pull requests, and get them reviewed by a peer).

Generally, contributing to a doc will imply:

  1. commenting on the issue to announce you're planning to work on it,
  2. looking at existing docs to find related content,
  3. using an online service to convert that content to Markdown,
  4. copyediting it,
  5. adding YAML front-matter,
  6. signing the Contributor License Agreement, and
  7. sending a pull request.

Thanks for your help!