Merge branch 'master' into next

This commit is contained in:
Vincent Prouillet 2018-12-14 17:35:50 +01:00 committed by GitHub
commit 5eebbc68de
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 240 additions and 107 deletions

23
.github/ISSUE_TEMPLATE/bug_report.md vendored Normal file
View file

@ -0,0 +1,23 @@
---
name: Bug Report
about: Did you run into an issue while using Zola?
---
# Bug Report
## Environment
Zola version:
## Expected Behavior
Tell us what should have happened.
## Current Behavior
Tell us what happens instead of the expected behavior. If you are seeing an
error, please include the full error message and stack trace. You can get the
stacktrace of a panic by adding `RUST_BACKTRACE=1` when running a `zola` command.
## Step to reproduce
Please provide the steps to reproduce the issue.
If the issue is hard to reproduce, please provide a sample repository or sample
that triggers the bug.

14
.github/ISSUE_TEMPLATE/documentation.md vendored Normal file
View file

@ -0,0 +1,14 @@
---
name: Documentation
about: Is the documentation lacking or has typos/errors/missing/outdated content?
---
# Documentation issue
## Summary
What is the issue? Is the documentation unclear? Is it missing information?
## Proposed solution
A quick explanation of what you would like to see to solve the issue.
If you want to add content, please explain what you were looking fod and what was
your process while looking at the current documentation.

20
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View file

@ -0,0 +1,20 @@
**IMPORTANT: Please do not create a Pull Request adding a new feature without discussing it first.**
The place to discuss new features is the forum: <https://zola.discourse.group/>
If you want to add a new feature, please open a thread there first in the feature requests section.
Sanity check:
* [ ] Have you checked to ensure there aren't other open [Pull Requests](../../pulls) for the same update/change?
## Code changes
(Delete or ignore this section for documentation changes)
* [ ] Are you doing the PR on the `next` branch?
If the change is a new feature or adding to/changing an existing one:
* [ ] Have you created/updated the relevant documentation page(s)?

66
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,66 @@
# Contributing
**As the documentation site is automatically built on commits to master, all development happens on
the `next` branch, unless it is fixing the current documentation.**
However, if you notice an error or typo in the documentation, feel free to directly submit a PR without opening an issue.
## Feature requests
If you want a feature added or modified, please open a thread on the [forum](https://zola.discourse.group/) to discuss it before doing a PR.
Requested features will not be all added: an ever-increasing features set makes for a hard to use and explain softwares.
Having something simple and easy to use for 90% of the usecases is more interesting than covering 100% usecases after sacrificing simplicity.
## Issues tagging
As the development happens on the `next` branch, issues are kept open until a release containing the fix is out.
During that time, issues already resolved will have a `done` tag.
If you want to work on an issue, please mention it in a comment to avoid potential duplication of work. If you have
any questions on how to approach it do not hesitate to ping me (@keats).
Easy issues are tagged with `help wanted` and/or `good first issue`
## Adding syntax highlighting languages and themes
### Adding a syntax
Syntax highlighting depends on submodules so ensure you load them first:
```bash
$ git submodule update --init
```
Zola only works with syntaxes in the `.sublime-syntax` format. If your syntax
is in `.tmLanguage` format, open it in Sublime Text and convert it to `sublime-syntax` by clicking on
Tools > Developer > New Syntax from ... and put it at the root of `sublime_syntaxes`.
You can also add a submodule to the repository of the wanted syntax:
```bash
$ cd sublime_syntaxes
$ git submodule add https://github.com/elm-community/SublimeElmLanguageSupport
```
Note that you can also only copy manually the updated syntax definition file but this means
Zola won't be able to automatically update it.
You can check for any updates to the current packages by running:
```bash
$ git submodule update --remote --merge
```
And finally from the root of the components/config crate run the following command:
```bash
$ cargo run --example generate_sublime synpack ../../sublime_syntaxes ../../sublime_syntaxes/newlines.packdump
```
### Adding a theme
A gallery containing lots of themes is located at https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark.
More themes can be easily added to Zola, just make a PR with the wanted theme added in the `sublime_themes` directory
and run the following command from the root of the components/config:
```bash
$ cargo run --example generate_sublime themepack ../../sublime_themes ../../sublime_themes/all.themedump
```
You should see the list of themes being added.

View file

@ -5,7 +5,7 @@
A fast static site generator in a single binary with everything built-in.
Documentation is available on [its site](https://www.getzola.org/documentation/getting-started/installation/) or
in the `docs/content` folder of the repository.
in the `docs/content` folder of the repository and the community can use [its forum](https://zola.discourse.group).
## Comparisons with other static site generators
@ -33,7 +33,7 @@ in the `docs/content` folder of the repository.
| LiveReload | ✔ | ✕ | ✔ | ✔ |
| Netlify support | ~ | ✕ | ✔ | ✕ |
| Breadcrumbs | ✔ | ✕ | ✕ | ✔ |
| Custom ouput formats | ✕ | ✕ | ✔ | ? |
| Custom output formats | ✕ | ✕ | ✔ | ? |
### Supported content formats
@ -53,55 +53,3 @@ Hugo gets `~`. It is probably the most powerful template engine in the list afte
Many features of Pelican are coming from plugins, which might be tricky
to use because of version mismatch or lacking documentation. Netlify supports Python
and Pipenv but you still need to install your dependencies manually.
## Contributing
As the documentation site is automatically built on commits to master, all development
should happen on the `next` branch, unless it is fixing the current documentation.
If you want a feature added or modified, please open an issue to discuss it before doing a PR.
### Adding syntax highlighting languages and themes
#### Adding a syntax
Syntax highlighting depends on submodules so ensure you load them first:
```bash
$ git submodule update --init
```
Zola only works with syntaxes in the `.sublime-syntax` format. If your syntax
is in `.tmLanguage` format, open it in Sublime Text and convert it to `sublime-syntax` by clicking on
Tools > Developer > New Syntax from ... and put it at the root of `sublime_syntaxes`.
You can also add a submodule to the repository of the wanted syntax:
```bash
$ cd sublime_syntaxes
$ git submodule add https://github.com/elm-community/SublimeElmLanguageSupport
```
Note that you can also only copy manually the updated syntax definition file but this means
Zola won't be able to automatically update it.
You can check for any updates to the current packages by running:
```bash
$ git submodule update --remote --merge
```
And finally from the root of the components/config crate run the following command:
```bash
$ cargo run --example generate_sublime synpack ../../sublime_syntaxes ../../sublime_syntaxes/newlines.packdump
```
#### Adding a theme
A gallery containing lots of themes is located at https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark.
More themes can be easily added to Zola, just make a PR with the wanted theme added in the `sublime_themes` directory
and run the following command from the root of the components/config:
```bash
$ cargo run --example generate_sublime themepack ../../sublime_themes ../../sublime_themes/all.themedump
```
You should see the list of themes being added.

View file

@ -3,7 +3,7 @@ title = "Image processing"
weight = 120
+++
Gutenberg provides support for automatic image resizing through the built-in function `resize_image`,
Zola provides support for automatic image resizing through the built-in function `resize_image`,
which is available in template code as well as in shortcodes.
The function usage is as follows:

View file

@ -0,0 +1,71 @@
+++
title = "GitLab Pages"
weight = 30
+++
We are going to use the GitLab CI runner to automatically publish the site (this CI runner is already included in your repository if you use GitLab.com).
## Repository setup
Your repository needs to be set up to be a user or group website. This means the name of the repository has to be in the correct format.
For example, under your username, `john`, you have to create a project called `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. Once you enable GitLab Pages for your project, your website will be published under `https://john.gitlab.io`.
Under your group `websites`, you created a project called `websites.gitlab.io`. Your projects URL will be `https://gitlab.com/websites/websites.gitlab.io`. Once you enable GitLab Pages for your project, your website will be published under `https://websites.gitlab.io`.
This guide assumes that your zola project is located in the root of your repository.
## Ensuring that the CI runner can access your theme
Depending on how you added your theme your repository may not contain it. The best way to ensure the theme will be added is to use
submodules. When doing this ensure you are using the `https` version of the URL.
```shell
$ git submodule add {THEME_URL} themes/{THEME_NAME}
```
For example, this could look like
```shell
$ git submodule add https://github.com/getzola/hyde.git themes/hyde
```
## Setting up the GitLab CI/CD Runner
The second step is to tell the gitlab continous integration runner how to create the gitlab page.
To do this, create a file called `.gitlab-ci.yml` in the root directory of your repository.
```yaml
variables:
# This variable will ensure that the CI runner pulls in your theme from the submodule
GIT_SUBMODULE_STRATEGY: recursive
# Specify the zola version you want to use here
ZOLA_VERSION: "v0.5.0"
pages:
script:
# Download the zola executable and store it in zola.tar.gz
- curl -L https://github.com/getzola/zola/releases/download/$ZOLA_VERSION/zola-$ZOLA_VERSION-x86_64-unknown-linux-gnu.tar.gz > zola.tar.gz
# Unpack the zola executable
- tar -xzf zola.tar.gz
# Execute zola build
- ./zola build
artifacts:
paths:
# Path of our artifacts
- public
# This config will only publish changes that are pushed on the master branch
only:
- master
```
Push this new file and... Tada! You're done! If you navigate to `settings > pages` you should be able to see something like this:
> Congratulations! Your pages are served under:
https://john.gitlab.io
More information on the process to host on GitLab pages and additional information like using a custom domain is documented
[in this GitLab blog post](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).

View file

@ -6,18 +6,52 @@ weight = 1
Zola provides pre-built binaries for MacOS, Linux and Windows on the
[GitHub release page](https://github.com/getzola/zola/releases).
## Arch Linux
### macOS
Use your favourite AUR helper to install the `zola-bin` package.
Zola is available on [Brew](https://brew.sh):
```bash
$ yaourt -S zola-bin
$ brew install zola
```
## From source
To build it from source, you will need to have Git, [Rust (at least 1.30) and Cargo](https://www.rust-lang.org/)
installed. You will also need additional dependencies to compile [libsass](https://github.com/sass/libsass):
### Arch Linux
Use your favourite AUR helper to install the `zola-bin` package.
```bash
$ yay -S zola-bin
```
### Snapcraft
Zola is available on snapcraft:
```bash
$ snap install --edge --classic zola
```
## Windows
Zola is available on [Scoop](http://scoop.sh):
```bash
$ scoop install zola
```
And [Chocolatey](https://chocolatey.org/):
```bash
$ choco install zola
```
## From source
To build it from source, you will need to have Git, [Rust (at least 1.29) and Cargo](https://www.rust-lang.org/)
installed. You will also need additional dependencies to compile [libsass](https://github.com/sass/libsass):
- OSX, Linux and other Unix: `make` (`gmake` on BSDs), `g++`, `libssl-dev`
- Windows (a bit trickier): updated `MSVC` and overall updated VS installation
@ -30,46 +64,3 @@ $ cargo build --release
The binary will be available in the `target/release` folder. You can move it in your `$PATH` to have the
`zola` command available globally or in a directory if you want for example to have the binary in the
same repository as the site.
## Older versions (Gutenberg)
Before 0.5, Zola was called Gutenberg. Since the process of updating package managers to Zola is on-going, you can still
download previous versions of Gutenberg on your package manager of choice in the meantime.
### macOS
Gutenberg is available on [Brew](https://brew.sh):
```bash
$ brew install gutenberg
```
### Windows
Gutenberg is available on [Scoop](http://scoop.sh):
```bash
$ scoop install gutenberg
```
And [Chocolatey](https://chocolatey.org/):
```bash
$ choco install gutenberg
```
### Arch Linux
Use your favourite AUR helper to install the `gutenberg-bin` package.
```bash
$ yaourt -S gutenberg-bin
```
### Void Linux
From the terminal, run the following command:
```bash
$ xbps-install -S gutenberg
```

View file

@ -1,8 +1,8 @@
{% for asset in page.assets %}
{% if asset is ending_with(".jpg") %}
<a href="{{ get_url(path=asset) }}">
<img src="{{ resize_image(path=asset, width=240, height=180, op="fill") }}" />
{% for asset in page.assets -%}
{%- if asset is ending_with(".jpg") -%}
<a href="{{ get_url(path=asset) | safe }}">
<img src="{{ resize_image(path=asset, width=240, height=180, op="fill") | safe }}" />
</a>
&ensp;
{% endif %}
{% endfor %}
{%- endif %}
{%- endfor %}