143 lines
5.7 KiB
Markdown
143 lines
5.7 KiB
Markdown
# Grav Archives Plugin
|
|
|
|
`Archives` is a [Grav](http://github.com/getgrav/grav) plugin that automatically appends a `month_year` taxonomy to all pages. It then provides a `partials\archives.html.twig` template which you can include in a blog sidebar, that then is able to create links that will display pages from that month/year. This is a very handy feature to have for blogs.
|
|
|
|
# Installation
|
|
|
|
Installing the Archives plugin can be done in one of two ways. Our GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
|
|
|
|
## GPM Installation (Preferred)
|
|
|
|
|
|
|
|
The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's Terminal (also called the command line). From the root of your Grav install type:
|
|
|
|
bin/gpm install archives
|
|
|
|
This will install the Archives plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/archives`.
|
|
|
|
## Manual Installation
|
|
|
|
To install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `archives`. You can find these files either on [GitHub](https://github.com/getgrav/grav-plugin-archives) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
|
|
|
|
You should now have all the plugin files under
|
|
|
|
/your/site/grav/user/plugins/archives
|
|
|
|
>> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) plugins, and a theme to be installed in order to operate.
|
|
|
|
# Usage
|
|
|
|
The `archives` plugin comes with some sensible default configuration, that are pretty self-explanatory:
|
|
|
|
# Config Defaults
|
|
|
|
```
|
|
enabled: true
|
|
built_in_css: true
|
|
date_display_format: 'F Y'
|
|
show_count: true
|
|
limit: 12
|
|
taxonomy_names:
|
|
month: archives_month
|
|
year: archives_year
|
|
#Defaults
|
|
order:
|
|
by: date
|
|
dir: desc
|
|
filters:
|
|
category: blog
|
|
filter_combinator: and
|
|
#New Page-Specific Configurations
|
|
page_specific_config:
|
|
- route: '/blog'
|
|
order:
|
|
by: date
|
|
dir: desc
|
|
filters:
|
|
page@: '/blog'
|
|
filter_combinator: and
|
|
```
|
|
|
|
If you need to change any value, then the best process is to copy the [archives.yaml](archives.yaml) file into your `users/config/plugins/` folder (create it if it doesn't exist), and then modify there. This will override the default settings.
|
|
|
|
## Filter Types
|
|
|
|
#### category
|
|
|
|
The legacy approach is to provide a specific category taxonomy filter, or multiple categories:
|
|
|
|
```
|
|
filters:
|
|
category 'blog-post'
|
|
```
|
|
|
|
#### taxonomy@
|
|
|
|
You can use sophisticated taxonomy filtering with the same mechanism as page taxonomy filtering:
|
|
|
|
```
|
|
filters:
|
|
taxonomy@.tag: photography # taxonomy called tag is set to photography
|
|
```
|
|
|
|
or:
|
|
|
|
```
|
|
filters:
|
|
taxonomy@: {tag: birds, category: blog} # taxonomy with tag=birds && category=blog
|
|
```
|
|
|
|
#### page@
|
|
|
|
You can reference a specific page's collection via the page@ filter:
|
|
|
|
```
|
|
filters:
|
|
page@: '/blog' # Use the collection defined in the header of `/blog` page
|
|
```
|
|
|
|
#### self@
|
|
|
|
You can also list the current children, without having to search for a taxonomy term by using
|
|
|
|
```
|
|
filters:
|
|
- self@ # use the children defined in the current page
|
|
```
|
|
|
|
# Template Override
|
|
|
|
Something you might want to do is to override the look and feel of the archives, and with Grav it is super easy.
|
|
|
|
Copy the template file [templates/partials/archives.html.twig](templates/partials/archives.html.twig) into the `templates/partials` folder of your custom theme, and that is it.
|
|
|
|
```
|
|
/your/site/grav/user/themes/custom-theme/templates/partials/archives.html.twig
|
|
```
|
|
|
|
You can now edit the override and tweak it however you prefer.
|
|
|
|
# Updating
|
|
|
|
As development for Archives continues, new versions may become available that add additional features and functionality, improve compatibility with newer Grav releases, and generally provide a better user experience. Updating Archives is easy, and can be done through Grav's GPM system, as well as manually.
|
|
|
|
## GPM Update (Preferred)
|
|
|
|
The simplest way to update this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm). You can do this with this by navigating to the root directory of your Grav install using your system's Terminal (also called command line) and typing the following:
|
|
|
|
bin/gpm update archives
|
|
|
|
This command will check your Grav install to see if your Archives plugin is due for an update. If a newer release is found, you will be asked whether or not you wish to update. To continue, type `y` and hit enter. The plugin will automatically update and clear Grav's cache.
|
|
|
|
## Manual Update
|
|
|
|
Manually updating Archives is pretty simple. Here is what you will need to do to get this done:
|
|
|
|
* Delete the `your/site/user/plugins/archives` directory.
|
|
* Downalod the new version of the Archives plugin from either [GitHub](https://github.com/getgrav/grav-plugin-archives) or [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
|
|
* Unzip the zip file in `your/site/user/plugins` and rename the resulting folder to `archives`.
|
|
* Clear the Grav cache. The simplest way to do this is by going to the root Grav directory in terminal and typing `bin/grav clear-cache`.
|
|
|
|
> Note: Any changes you have made to any of the files listed under this directory will also be removed and replaced by the new set. Any files located elsewhere (for example a YAML settings file placed in `user/config/plugins`) will remain intact.
|