diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..3bde46a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -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. diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..d046687 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -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. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8853354 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -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: +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)? + + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f8b6645 --- /dev/null +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index 91740cb..00657b0 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/content/documentation/content/image-processing/index.md b/docs/content/documentation/content/image-processing/index.md index 61e6da4..d3c4799 100644 --- a/docs/content/documentation/content/image-processing/index.md +++ b/docs/content/documentation/content/image-processing/index.md @@ -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: diff --git a/docs/content/documentation/deployment/gitlab-pages.md b/docs/content/documentation/deployment/gitlab-pages.md new file mode 100644 index 0000000..73bb2b0 --- /dev/null +++ b/docs/content/documentation/deployment/gitlab-pages.md @@ -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 project’s 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/). diff --git a/docs/content/documentation/getting-started/installation.md b/docs/content/documentation/getting-started/installation.md index 9b37b43..c1ac908 100644 --- a/docs/content/documentation/getting-started/installation.md +++ b/docs/content/documentation/getting-started/installation.md @@ -6,70 +6,61 @@ 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): -- OSX, Linux and other Unix: `make` (`gmake` on BSDs), `g++`, `libssl-dev` -- Windows (a bit trickier): updated `MSVC` and overall updated VS installation +### Arch Linux -From a terminal, you can now run the following command: +Use your favourite AUR helper to install the `zola-bin` package. ```bash -$ cargo build --release +$ yay -S zola-bin ``` -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 +### Snapcraft -Gutenberg is available on [Brew](https://brew.sh): +Zola is available on snapcraft: ```bash -$ brew install gutenberg +$ snap install --edge --classic zola ``` -### Windows +## Windows -Gutenberg is available on [Scoop](http://scoop.sh): +Zola is available on [Scoop](http://scoop.sh): ```bash -$ scoop install gutenberg +$ scoop install zola ``` And [Chocolatey](https://chocolatey.org/): ```bash -$ choco install gutenberg +$ choco install zola ``` -### Arch Linux - -Use your favourite AUR helper to install the `gutenberg-bin` package. - -```bash -$ yaourt -S gutenberg-bin -``` +## 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): -### Void Linux +- OSX, Linux and other Unix: `make` (`gmake` on BSDs), `g++`, `libssl-dev` +- Windows (a bit trickier): updated `MSVC` and overall updated VS installation -From the terminal, run the following command: +From a terminal, you can now run the following command: ```bash -$ xbps-install -S gutenberg +$ 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. diff --git a/docs/templates/shortcodes/gallery.html b/docs/templates/shortcodes/gallery.html index d2afc71..a9261e9 100644 --- a/docs/templates/shortcodes/gallery.html +++ b/docs/templates/shortcodes/gallery.html @@ -1,8 +1,8 @@ -{% for asset in page.assets %} - {% if asset is ending_with(".jpg") %} - - +{% for asset in page.assets -%} + {%- if asset is ending_with(".jpg") -%} + +   - {% endif %} -{% endfor %} + {%- endif %} +{%- endfor %}