KiCad Website Source
====================

This the source for the new KiCad website, anno 2015.

LICENSE
=======

The kicad-website repository is dual licensed. 
You may distribute it and/or modify it under the terms of either
the GNU General Public License (http://www.gnu.org/licenses/gpl.html),
version 3 or later, or the Creative Commons Attribution License
(http://creativecommons.org/licenses/by/3.0/), version 3.0 or later.

== Prerequisites
You will need these packages:

- http://gohugo.io/[hugo] version 0.69.0 (you must use this version!)
- https://www.ruby-lang.org[ruby] (to use asciidoctor)
- http://asciidoctor.org/[asciidoctor] version 2.0.10

Using asciidoctor is a requirement, because the original asciidoc
runs into trouble parsing the adoc files with TOML headers in them.
asciidoctor also has a few extra features for web pages. 

== Testing

Execute the hugo command in the repository root to build and serve the
files for development:

----
hugo server -w -v
----

Observe the console output as it will tell you the address where the
page is accessible in a browser.  The -w flag tells it to watch the
filesystem for changes to rebuild automatically. Also, the page in the
browser will autorefresh once the rebuild completes successfully.

== Contributing
Please read the link:CONTRIBUTING.adoc[CONTRIBUTING Guidelines]

== Docker
A dockerfile is included that builds and packages the website with an nginx instance

== Hints
=== Admonition icons
For icons to appear in admonition blocks, you must add 
```
:icons: 
:iconsdir: /img/icons/
```
at the top of the asciidoc file but below the hugo template header.

=== adoc partials
Please name any reusable asciidoc files with a leading underscore in the filename and ending in .adoc.
Hugo is configured to ignore such files on purpose.

== External resources
To enhance security a little, we implement Content-Security-Policy headers which are set by nginx.
These dictate to the browser what resource paths are allowable for scripts, videos, images, etc
And while we do use HTTPS, CSP is just another tool to _potentially_ stop browser side and other attacks.

This means:
1. Please add any images, js and css directly to this repo. Its far better for us to mirror them lest they potentially go down in the future. Especially third party images
2. Please make best effort to use existing "approved" remote resources as visibile in /.docker/default.conf
3. If you notice a resource isn't loading on what you are editing, check the Developer Tools Console output for your respective browser, if it is blocked due to CSP, it will say so.