merge !242

resolves #194 document that .nojekyll is required to publish site to GitHub Pages

CHANGELOG.adoc

@@ -24,6 +24,10 @@ This project utilizes semantic versioning.
 * *content-aggregator*: Fetch all tags when the runtime pull option is enabled (#271)
 * *navigation-builder*: Allow navigation sublists to be enclosed in open blocks (#265)
 
+=== Documented
+
+* Document that a .nojekyll file is required to publish an Antora-generated site to GitHub Pages (#194)
+
 == 1.0.1 (2018-05-06)
 
 === Improved

docs/modules/ROOT/nav.adoc

@@ -14,6 +14,7 @@
 * xref:run-antora.adoc[Run Antora]
 ** xref:run-antora.adoc#cache[About the Cache]
 ** xref:run-antora.adoc#local-site-preview[Local Preview]
+** xref:run-antora.adoc#publish-to-github-pages[Publish to GitHub Pages]
 ** xref:antora-container.adoc[Run Antora in a Container]
 ** xref:cli:index.adoc[CLI Reference]
 

docs/modules/ROOT/pages/run-antora.adoc

@@ -247,3 +247,25 @@ These subsequent runs complete much faster because only the changes to the repos
 The repositories are cached under the [.path]_build/sources/_ directory.
 If you remove the [.path]_build/_ directory, the repositories will have to be downloaded again from scratch.
 ////
+
+== Publish to GitHub Pages
+
+Antora is designed to create sites that run anywhere, whether it be a static web host or the local filesystem.
+However, some hosts offer "`features`" that interfere with Antora's output.
+GitHub Pages is one of those hosts.
+
+By default, GitHub Pages runs all files through another static site generator named Jekyll.
+Since Antora already produces a ready-made site, there's no need for this.
+It's also problematic since Jekyll has the nasty side effect of removing all files that begin with an underscore (`+_+`).
+Antora puts UI files in a directory named `+_+`, which Jekyll subsequently erases.
+As a result, no UI.
+Antora also puts images in a folder named `_images` inside each module, so no images either.
+
+Fortunately, there's a way to disable this "`feature`" of GitHub Pages.
+The solution is to add a [.path]_.nojekyll_ file to the root of the published site.
+Simply create an empty [.path]_.nojekyll_ file in the output directory before committing the files to GitHub Pages.
+
+ $ touch build/site/.nojekyll
+
+The presence of the [.path]_.nojekyll_ file at the root of the `gh-pages` branch tells GitHub Pages not to run the published files through Jekyll.
+The result is that your Antora-made site will work as expected (and will be available sooner).