From b3c98ba6521209d9787cf0c9421056601bc6d583 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?=
 <bjorn.erik.pedersen@gmail.com>
Date: Sat, 18 Nov 2017 12:54:25 +0100
Subject: [PATCH] Add doc about the new static dir support

---
 content/content-management/static-files.md    | 45 +++++++++++++++++++
 .../getting-started/directory-structure.md    |  7 ++-
 2 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 content/content-management/static-files.md

diff --git a/content/content-management/static-files.md b/content/content-management/static-files.md
new file mode 100644
index 000000000..c8ad75de3
--- /dev/null
+++ b/content/content-management/static-files.md
@@ -0,0 +1,45 @@
+---
+title: Static Files
+description: "The `static` folder is where you place all your **static files**."
+date: 2017-11-18
+categories: [content management]
+keywords: [source, directories]
+menu:
+  docs:
+    parent: "content-management"
+    weight: 130
+weight: 130	#rem
+aliases: [/static-files]
+toc: true
+---
+
+The `static` folder is where you place all your **static files**, e.g. stylesheets, JavaScript, images etc.
+
+You can set the name of the static folder to use in your configuration file, for example `config.toml`.  From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem.
+
+Example:
+
+```toml
+staticDir = ["static1", "static2"]
+[languages]
+[languages.no]
+staticDir = ["staticDir_override", "static_no"]
+baseURL = "https://example.no"
+languageName = "Norsk"
+weight = 1
+title = "På norsk"
+
+[languages.en]
+staticDir2 = "static_en"
+baseURL = "https://example.com"
+languageName = "English"
+weight = 2
+title = "In English"
+```
+
+In the above, with no theme used:
+
+* The English site will get its static files as a union of "static1", "static2" and "static_en". On file duplicates, the right-most version will win.
+* The Norwegian site will get its static files as a union of "staticDir_override" and "static_no".
+
+**Note:** The example above is a [multihost setup](/content-management/multilingual/#configure-multilingual-multihost). In a regular setup, all the static directories will be available to all sites.
diff --git a/content/getting-started/directory-structure.md b/content/getting-started/directory-structure.md
index b5dc9a2ff..2403d1812 100644
--- a/content/getting-started/directory-structure.md
+++ b/content/getting-started/directory-structure.md
@@ -57,9 +57,13 @@ used by Hugo when generating your website. You can write these files in YAML, JS
 [`layouts`][]
 : Stores templates in the form of `.html` files that specify how views of your content will be rendered into a static website. Templates include [list pages][lists], your [homepage][], [taxonomy templates][], [partials][], [single page templates][singles], and more.
 
-`static`
+[`static`][]
 : stores all the static content for your future website: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content.
 
+{{% note %}}
+From **Hugo 0.31** you can have multiple static directories.
+{{% /note %}}
+
 {{% note %}}
 Hugo does not currently ship with an asset pipeline ([#3207](https://github.com/gohugoio/hugo/issues/3207)). You can solicit support from the community in the [Hugo forums](https://discourse.gohugo.io) or check out a few of the [Hugo starter kits](/tools/starter-kits/) for examples of how Hugo developers are managing static assets.
 {{% /note %}}
@@ -73,6 +77,7 @@ Hugo does not currently ship with an asset pipeline ([#3207](https://github.com/
 [data templates]: /templates/data-templates/
 [homepage]: /templates/homepage/
 [`layouts`]: /templates/
+[`static`]: /content-management/static-files/
 [lists]: /templates/list/
 [pagevars]: /variables/page/
 [partials]: /templates/partials/