mirror of
https://github.com/danog/sass-site.git
synced 2024-11-30 04:29:17 +01:00
105 lines
3.5 KiB
Markdown
105 lines
3.5 KiB
Markdown
# 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][ig] and the [Style Guide][sg]**
|
|
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 and Yarn
|
|
|
|
We recommend using [nvm](https://github.com/nvm-sh/nvm) for node version
|
|
management. [Install it](https://github.com/nvm-sh/nvm#installation-and-update)
|
|
if necessary, then run `nvm install` (once per active shell) to use the correct
|
|
version of node for development.
|
|
|
|
The correct [Yarn](https://yarnpkg.com/) version is included in the repo, and
|
|
will be used automatically for any `yarn` command.
|
|
|
|
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`
|
|
|
|
To upgrade the yarn version, run `yarn set version latest`, then update the
|
|
version number in `netlify.toml` and `package.json` (`engines.yarn` field) if
|
|
necessary.
|
|
|
|
### Install dependencies
|
|
|
|
```
|
|
yarn
|
|
```
|
|
|
|
### Development tasks
|
|
|
|
Compile and run [Eleventy](https://www.11ty.dev/) server, with a watcher for
|
|
file changes:
|
|
|
|
```
|
|
yarn 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
|
|
yarn build
|
|
|
|
# format and lint all files
|
|
yarn lint
|
|
```
|
|
|
|
## Templates
|
|
|
|
- `.liquid` files are parsed as [LiquidJS](https://liquidjs.com/) templates.
|
|
- To embed Markdown (or other languages) inside LiquidJS templates, use either
|
|
the `{% markdown %}` tag or the [11ty `{% renderTemplate 'md' %}`
|
|
tag](https://www.11ty.dev/docs/plugins/render/#rendertemplate). With the
|
|
latter, note that multiple languages can be used, e.g.
|
|
`{% renderTemplate 'liquid,md' %}`
|
|
- To include partials, use either the
|
|
[11ty `{% renderFile %}` tag](https://www.11ty.dev/docs/plugins/render/#renderfile)
|
|
or the [LiquidJS `{% render %}` tag](https://liquidjs.com/tags/render.html).
|
|
- 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
|
|
|
|
[ig]: https://sass-lang.com/implementation
|
|
[sg]: https://sass-lang.com/styleguide
|
|
[Netlify]: https://www.netlify.com/
|