sass-site/CONTRIBUTING.md

Contributing to the Sass website

The Sass website is open source. See a bug or typo? Have an idea? Do the following:

• Please read the Implementation Guide and the Style Guide before contributing.
• Write a detailed description of what you're adding in the pull request (screenshots help).
• If there is new design or CSS, please add @Jina as a reviewer so she can see if it needs to be added to the style guide (or if a suitable alternative exists).
• Submit the pull request to the main branch.
• Drink whisky.

Running Locally

Install Node

We recommend using nvm for node version management. Install it if necessary, then run nvm install (once per active shell) to use the correct version of node for development.

To upgrade the node version used by the Sass website, update the version number in these places and then run nvm install to upgrade:

• package.json (engines.node field)
• .nvmrc
• netlify.toml
• Dockerfile

Install dependencies

npm install

Development tasks

Compile and run Eleventy server, with a watcher for file changes:

npm run serve

The site will be compiled into _site/ and available at http://localhost:8080.

You can also run individual commands:

# build the static site for development
npm run build

# format and lint all files
npm run lint

Templates

• .liquid files are parsed as LiquidJS templates.
  • To embed Markdown (or other languages) inside LiquidJS templates, use either the {% markdown %} tag or the 11ty {% renderTemplate 'md' %} tag. With the latter, note that multiple languages can be used, e.g. {% renderTemplate 'liquid,md' %}
  • To include partials, use either the 11ty {% renderFile %} tag or the LiquidJS {% render %} tag.
    • Note that renderFile requires a relative path from the root directory, while render uses a relative path from the /source/_includes/ directory.
    • Both tags create an encapsulated scope for the partial, so any variables used in the partial must be explicitly passed in.
    • renderFile allows overriding the template language (e.g. {% renderFile 'source/_includes/footer_nav.md', data, 'liquid,md' %}), while render always parses the partial as a LiquidJS template.
• .md files are parsed both as Markdown and as LiquidJS templates.
• When using Markdown, remember that indentation and whitespace (e.g newlines) matter. Use Markdown selectively, especially in files that include other non-Markdown partials.
  • For example, the {% codeExample %} tag renders whitespace that results in unwanted <p> tags when parsed as Markdown.

Deploying

Every time a new commit is pushed to main, it will automatically be deployed to sass-lang.com via Netlify. Easy as that!

Thanks!

— Sass Core Team