You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pagespeed.apache.org by os...@apache.org on 2019/05/16 08:13:48 UTC
[incubator-pagespeed-website] branch master created (now b756aa4)
This is an automated email from the ASF dual-hosted git repository.
oschaaf pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pagespeed-website.git.
at b756aa4 Move in incubator-pagespeed-mod/html
This branch includes the following new commits:
new 15d0221 Skeleton for the PageSpeed podling website
new b756aa4 Move in incubator-pagespeed-mod/html
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[incubator-pagespeed-website] 01/02: Skeleton for the PageSpeed
podling website
Posted by os...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
oschaaf pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pagespeed-website.git
commit 15d0221e304919d44c716966a368810ca1b08b73
Author: Otto van der Schaaf <os...@we-amp.com>
AuthorDate: Thu May 16 10:11:26 2019 +0200
Skeleton for the PageSpeed podling website
Signed-off-by: Otto van der Schaaf <os...@we-amp.com>
---
.gitignore | 39 ++++++++++++
LICENSE | 202 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.md | 1 +
3 files changed, 242 insertions(+)
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..a7a848e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,39 @@
+logs
+*.log
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+*~
+.directory
+.Trash-*
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+*.cab
+*.msi
+*.msm
+*.msp
+*.lnk
+.dropbox
+.dropbox.attr
+.dropbox.cache
+*.tmlanguage.cache
+*.tmPreferences.cache
+*.stTheme.cache
+*.sublime-workspace
+sftp-config.json
+.settings/
+.vscode/
\ No newline at end of file
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..31923a3
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2010 Google Inc.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..61b6447
--- /dev/null
+++ b/README.md
@@ -0,0 +1 @@
+This repository contains the website for the incubating PageSpeed project.
[incubator-pagespeed-website] 02/02: Move in
incubator-pagespeed-mod/html
Posted by os...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
oschaaf pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pagespeed-website.git
commit b756aa4a73e4fe505f67597fd172716604c396b8
Author: Otto van der Schaaf <os...@we-amp.com>
AuthorDate: Thu May 16 10:13:08 2019 +0200
Move in incubator-pagespeed-mod/html
Signed-off-by: Otto van der Schaaf <os...@we-amp.com>
---
doc/.htaccess | 38 +
doc/CVE-2012-4001.html | 59 +
doc/CVE-2012-4360.html | 49 +
doc/CVE-2013-6111.html | 80 +
doc/_footer.html | 110 +
doc/_header.html | 34 +
doc/_navline.html | 22 +
doc/admin.html | 411 ++
doc/analytics_screenshots/10_histogram.png | Bin 0 -> 88271 bytes
doc/analytics_screenshots/1_login.png | Bin 0 -> 34224 bytes
.../2_import_advanced_segment.png | Bin 0 -> 19527 bytes
doc/analytics_screenshots/3_segment_settings.png | Bin 0 -> 44501 bytes
doc/analytics_screenshots/4_profile_switch.png | Bin 0 -> 27378 bytes
doc/analytics_screenshots/5_profile_switched.png | Bin 0 -> 30339 bytes
doc/analytics_screenshots/6_standard_reporting.png | Bin 0 -> 53056 bytes
doc/analytics_screenshots/7_page_timings.png | Bin 0 -> 80962 bytes
doc/analytics_screenshots/8_advanced_segments.png | Bin 0 -> 40933 bytes
doc/analytics_screenshots/9_page_level_timings.png | Bin 0 -> 55774 bytes
doc/announce-0.10.22.6.html | 68 +
doc/announce-ngx-sec-update-201310.html | 102 +
doc/announce-sec-update-201310.html | 418 ++
doc/announce-sec-update-201601.html | 123 +
doc/announce-sec-update-201603.html | 168 +
doc/build_from_source.html | 45 +
doc/build_mod_pagespeed_from_source.html | 341 ++
doc/build_ngx_pagespeed_from_source.html | 203 +
doc/config_filters.html | 1004 +++++
doc/configuration.html | 638 +++
doc/console.html | 223 +
doc/doc.css | 212 +
doc/domains.html | 1025 +++++
doc/download.html | 133 +
doc/downstream-caching.html | 521 +++
doc/experiment.html | 449 ++
doc/faq.html | 777 ++++
doc/filter-attribute-elide.html | 119 +
doc/filter-cache-extend-pdfs.html | 83 +
doc/filter-cache-extend.html | 219 +
doc/filter-canonicalize-js.html | 293 ++
doc/filter-comment-remove.html | 129 +
doc/filter-convert-meta-tags.html | 78 +
doc/filter-css-above-scripts.html | 152 +
doc/filter-css-combine.html | 216 +
doc/filter-css-inline-google-fonts.html | 162 +
doc/filter-css-inline-import.html | 112 +
doc/filter-css-inline.html | 157 +
doc/filter-css-outline.html | 182 +
doc/filter-css-rewrite.html | 215 +
doc/filter-css-to-head.html | 143 +
doc/filter-dedup-inlined-images.html | 110 +
doc/filter-domain-rewrite.html | 95 +
doc/filter-flatten-css-imports.html | 165 +
doc/filter-head-add.html | 98 +
doc/filter-head-combine.html | 141 +
doc/filter-hint-preload-subresources.html | 123 +
doc/filter-image-optimize.html | 603 +++
doc/filter-image-responsive.html | 162 +
doc/filter-image-sprite.html | 187 +
doc/filter-inline-preview-images.html | 155 +
doc/filter-insert-dns-prefetch.html | 114 +
doc/filter-insert-ga.html | 81 +
doc/filter-instrumentation-add.html | 215 +
doc/filter-js-combine.html | 147 +
doc/filter-js-defer.html | 154 +
doc/filter-js-inline.html | 168 +
doc/filter-js-minify.html | 206 +
doc/filter-js-outline.html | 167 +
doc/filter-lazyload-images.html | 180 +
doc/filter-local-storage-cache.html | 149 +
doc/filter-make-google-analytics-async.html | 171 +
doc/filter-make-show-ads-async.html | 164 +
doc/filter-pedantic.html | 92 +
doc/filter-prioritize-critical-css.html | 178 +
doc/filter-quote-remove.html | 109 +
doc/filter-rewrite-style-attributes.html | 118 +
doc/filter-source-maps-include.html | 141 +
doc/filter-strip-scripts.html | 58 +
doc/filter-trim-urls.html | 122 +
doc/filter-whitespace-collapse.html | 143 +
doc/filters.html | 158 +
doc/https_support.html | 392 ++
doc/images/admin_config.png | Bin 0 -> 6903 bytes
doc/images/downstream_caching.png | Bin 0 -> 52190 bytes
doc/images/purge_entire_cache.png | Bin 0 -> 10616 bytes
doc/images/purge_one_url.png | Bin 0 -> 10955 bytes
.../puzzle_optimized_to_low_quality_webp.webp | Bin 0 -> 25760 bytes
...imized_to_low_quality_webp_and_saved_as_png.png | Bin 0 -> 544929 bytes
doc/images/puzzle_original.jpg | Bin 0 -> 241260 bytes
doc/index.html | 131 +
doc/mailing-lists.html | 74 +
doc/mod_security.html | 81 +
doc/module-run-experiment.html | 458 ++
doc/openssl-1.0.1h-fixes.html | 71 +
doc/optimize-for-bandwidth.html | 132 +
doc/reference-image-optimize.html | 799 ++++
doc/release_notes.html | 4709 ++++++++++++++++++++
doc/restricting_urls.html | 300 ++
doc/system.html | 1343 ++++++
incubator.png | Bin 0 -> 30207 bytes
index.html | 291 ++
network-loading.png | Bin 0 -> 152825 bytes
pagespeed+nginx+apache.svg | 658 +++
102 files changed, 23826 insertions(+)
diff --git a/doc/.htaccess b/doc/.htaccess
new file mode 100644
index 0000000..38821b0
--- /dev/null
+++ b/doc/.htaccess
@@ -0,0 +1,38 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Turn on server side include processing for the header inclusion.
+AddOutputFilter INCLUDES .html
+Options +Includes
+Options +FollowSymLinks
+
+# Make /foo.html available at /foo
+RewriteEngine on
+RewriteCond %{REQUEST_FILENAME}.html -f
+RewriteRule !.*\.html$ %{REQUEST_FILENAME}.html [L]
+
+# Turn on mod_pagespeed to optimize our docs.
+ModPagespeed on
+ModPagespeedRewriteLevel CoreFilters
+ModPagespeedEnableFilters collapse_whitespace
+ModPagespeedEnableFilters remove_comments
+ModPagespeedInPlaceResourceOptimization on
+
+# Do not optimize these resources which are used for blogpost
+ModPagespeedDisallow */puzzle_optimized_to_low_quality_webp.webp
+ModPagespeedDisallow */puzzle_optimized_to_low_quality_webp_and_saved_as_png.png
+ModPagespeedDisallow */puzzle_original.jpg
diff --git a/doc/CVE-2012-4001.html b/doc/CVE-2012-4001.html
new file mode 100644
index 0000000..97be44f
--- /dev/null
+++ b/doc/CVE-2012-4001.html
@@ -0,0 +1,59 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>mod_pagespeed Security Advisory: Insufficient Hostname Verification</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>mod_pagespeed Security Advisory: Insufficient Hostname Verification</h1>
+<dl>
+ <dt>CVE Identifier:</dt>
+ <dd>CVE-2012-4001</dd>
+ <dt>Disclosed:</dt>
+ <dd>September 12, 2012</dd>
+ <dt>Versions Affected:</dt>
+ <dd>All versions of mod_pagespeed up to and including 0.10.22.4.</dd>
+ <dt>Summary:</dt>
+ <dd>mod_pagespeed performs insufficient verification of its own host name,
+ which makes it possible to trick it into doing HTTP fetches and resource
+ processing from arbitrary host names, including potentially bypassing
+ firewalls.</dd>
+ <dt>Solution:</dt>
+ <dd>mod_pagespeed 0.10.22.6 has been released with a fix.</dd>
+ <dt>Workaround:</dt>
+ <dd>If you are unable to upgrade to the new version, you can avoid this
+ issue by changing your Apache httpd configuration. Give any virtual host
+ that enables mod_pagespeed (and the global configuration, if it also enables
+ mod_pagespeed) an accurate explicit <code>ServerName</code>, and set the
+ options <code>UseCanonicalName</code> and
+ <code>UseCanonicalPhysicalPort</code> to <code>On</code> in each. Please be
+ aware, however, that depending on the version,
+ <a href="CVE-2012-4360">CVE-2012-4360</a> may also apply.
+ </dd>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/CVE-2012-4360.html b/doc/CVE-2012-4360.html
new file mode 100644
index 0000000..ee824f3
--- /dev/null
+++ b/doc/CVE-2012-4360.html
@@ -0,0 +1,49 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>mod_pagespeed Security Advisory: Cross-Site Scripting</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>mod_pagespeed Security Advisory: Cross-Site Scripting</h1>
+<dl>
+ <dt>CVE Identifier:</dt>
+ <dd>CVE-2012-4360</dd>
+ <dt>Disclosed:</dt>
+ <dd>September 12, 2012</dd>
+ <dt>Versions Affected:</dt>
+ <dd>mod_pagespeed versions 0.10.19.1 through 0.10.22.4 (inclusive).
+ Versions 0.9.18.6 and earlier are unaffected.</dd>
+ <dt>Summary:</dt>
+ <dd>mod_pagespeed performs insufficient escaping in some cases, which can
+ permit a hostile 3rd party to inject JavaScript running in context of
+ the site.</dd>
+ <dt>Solution:</dt>
+ <dd>mod_pagespeed 0.10.22.6 has been released with a fix.</dd>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/CVE-2013-6111.html b/doc/CVE-2013-6111.html
new file mode 100644
index 0000000..245abf6
--- /dev/null
+++ b/doc/CVE-2013-6111.html
@@ -0,0 +1,80 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>mod_pagespeed and ngx_pagespeed Security Advisory: Cross-Site Scripting</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>mod_pagespeed and ngx_pagespeed Security Advisory: Cross-Site Scripting</h1>
+<dl>
+ <dt>CVE Identifier:</dt>
+ <dd><p>CVE-2013-6111</p></dd>
+ <dt>Disclosed:</dt>
+ <dd><p>October 28th, 2013</p></dd>
+ <dt>Versions Affected:</dt>
+ <dd>
+ <ul>
+ <li>mod_pagespeed versions earlier than 1.0</li>
+ <li>mod_pagespeed version 1.0.22.7 (fixed in 1.0.22.8)</li>
+ <li>mod_pagespeed versions 1.1</li>
+ <li>mod_pagespeed 1.2.24.1 (fixed in 1.2.24.2)</li>
+ <li>mod_pagespeed 1.3.25.1 through 1.3.25.4 (fixed in 1.3.25.5)</li>
+ <li>mod_pagespeed 1.4.26.1 through 1.4.26.4 (fixed in 1.4.26.5)</li>
+ <li>mod_pagespeed and ngx_pagespeed 1.5.27.1 through 1.5.27.3 (fixed in 1.5.27.4)</li>
+ <li>mod_pagespeed and ngx_pagespeed 1.6.29.1 through 1.6.29.6 (fixed in 1.6.29.7)</li>
+ </ul>
+ </dd>
+ <dt>Summary:</dt>
+ <dd><p>Some versions of mod_pagespeed and ngx_pagespeed are vulnerable to
+ cross-site scripting (XSS), which can permit a hostile 3rd party to
+ inject javascript running in the context of the site.</p></dd>
+ <dt>Solution:</dt>
+ <dd><p>For mod_pagespeed, update to one of versions 1.0.22.8-stable,
+ 1.2.24.2-stable, 1.3.25.5-stable, 1.4.26.5-stable, 1.5.27.4-beta, or
+ 1.6.29.7 or newer.</p>
+
+ <p>For ngx_pagespeed, update to 1.6.29.7 or newer.</p>
+ </dd>
+ <dt>Workaround:</dt>
+ <dd>
+ <p>No workaround is available for mod_pagespeed.</p>
+
+ <p>For ngx_pagespeed, you can completely prohibit access to
+ <code>/ngx_pagespeed_statistics</code>,
+ <code>/ngx_pagespeed_global_statistics</code> and
+ <code>/ngx_pagespeed_message</code> (an IP whitelist is insufficient), via
+ options similar to:
+<pre>
+location /ngx_pagespeed_global_statistics { deny all; }
+location /ngx_pagespeed_statistics { deny all; }
+location /ngx_pagespeed_message { deny all; }
+</pre>
+ </p>
+ </dd>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/_footer.html b/doc/_footer.html
new file mode 100644
index 0000000..ca41793
--- /dev/null
+++ b/doc/_footer.html
@@ -0,0 +1,110 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<div id=footer>
+ <!--#include virtual="_navline.html" -->
+</div>
+
+<script>
+function buildTocHelper(node, headers) {
+ if (node.nodeType == 1) {
+ // Element node.
+ var nodeName = node.nodeName.toLowerCase();
+ if (nodeName == "h2" || nodeName == "h3" || nodeName == "h4" ||
+ nodeName == "h5" || nodeName == "h6") {
+ if (node.id) {
+ headers.push([nodeName, node.innerHTML, node.id]);
+ node.appendChild(document.createTextNode("\u00A0")); // nbsp
+ var a = document.createElement("a");
+ a.class = "header-link";
+ a.href = "#" + node.id;
+ a.textContent = "\uD83D\uDD17"; // link symbol
+ node.appendChild(a);
+ }
+ } else {
+ for (var i = 0; i < node.childNodes.length; i++) {
+ buildTocHelper(node.childNodes[i], headers);
+ }
+ }
+ }
+}
+
+function buildToc() {
+ var headers = [];
+ buildTocHelper(document.body, headers);
+ if (headers.length == 0) {
+ return;
+ }
+
+ var toc = document.getElementById("toc");
+ var tocContents = document.createElement("div");
+ tocContents.id = "toc-contents";
+ tocContents.textContent = "Contents";
+ toc.appendChild(tocContents);
+
+ var level = 1;
+ var currentUl = null;
+ for (var i = 0; i < headers.length; i++) {
+ var header = headers[i];
+ var headerLevel = header[0];
+ var headerValue = header[1];
+ var headerId = header[2];
+
+ var newLevel = parseInt(headerLevel.substring(1));
+ while (newLevel > level) {
+ // We loop here to handle the case where we have h2 ... h4. This
+ // isn't a good way to write html, but someone may still do it.
+
+ var newUl = document.createElement("ul");
+ if (currentUl == null) {
+ toc.appendChild(newUl);
+ } else {
+ currentUl.appendChild(newUl);
+ }
+ currentUl = newUl;
+ level++;
+ }
+ while (newLevel < level) {
+ currentUl = currentUl.parentNode;
+ level--;
+ }
+ var li = document.createElement("li");
+ var a = document.createElement("a");
+ a.href = "#" + headerId;
+ a.textContent = headerValue;
+ li.appendChild(a);
+ currentUl.appendChild(li);
+ }
+}
+
+function wrapTables() {
+ var tables = document.getElementsByTagName("table");
+ for (var i = 0; i < tables.length; i++) {
+ var table = tables[i];
+ var parent = table.parentNode;
+ var div = document.createElement('div');
+ div.className = "table-wrapper";
+ parent.insertBefore(div, table);
+ div.appendChild(table);
+ }
+}
+
+buildToc();
+wrapTables();
+</script>
diff --git a/doc/_header.html b/doc/_header.html
new file mode 100644
index 0000000..6586f0d
--- /dev/null
+++ b/doc/_header.html
@@ -0,0 +1,34 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<div id=header>
+ <div id=logoline>
+ <div id=logo>
+ <img src="https://www.gstatic.com/images/branding/product/1x/pagespeed_32dp.png"
+ srcset="https://www.gstatic.com/images/branding/product/2x/pagespeed_32dp.png"
+ width=32 height=32 alt="pagespeed logo">
+ </div>
+ <div id=logotext>Apache PageSpeed (Incubating)</div>
+ </div>
+ <div id=navline>
+ <a href="/doc/">← documentation index</a>
+ </div>
+</div>
+<div id=toc></div>
+<img src="/incubator.png" height="80" align="right">
diff --git a/doc/_navline.html b/doc/_navline.html
new file mode 100644
index 0000000..8eb1431
--- /dev/null
+++ b/doc/_navline.html
@@ -0,0 +1,22 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<div id=navline>
+ <a href="/doc/">← documentation index</a>
+</div>
diff --git a/doc/admin.html b/doc/admin.html
new file mode 100644
index 0000000..fb85f73
--- /dev/null
+++ b/doc/admin.html
@@ -0,0 +1,411 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>PageSpeed Admin Pages</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>PageSpeed Admin Pages</h1>
+<p>
+ The admin pages are a collection of features that provide visibility
+ into the operation of the PageSpeed optimizations.
+</p>
+<p>
+The pagespeed_admin and pagespeed_global_admin pages aggregate a set of pages
+showing server state so they can be accessed from a single handler. By
+organizing all these features under a single admin page, this can be done once,
+and can serve as a launching point for future administration features.
+Before <strong>version 1.9.32.1</strong> the admin pages were read-only, but
+starting in <strong>version 1.9.32.1</strong>, cache purging is supported.
+</p>
+<img src="images/admin_config.png" style="border:1px solid black" />
+<p>
+ The name of the currently active page is underlined in the top navigation bar.
+</p>
+<table>
+ <thead>
+ <tr>
+ <th>Page</th>
+ <th>Related Options</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Statistics</td>
+ <td>
+ <a href="#statistics"><code>Statistics</code></a><br/>
+ <a href="#virtual-hosts-and-stats"
+ ><code>UsePerVHostStatistics</code></a><br/>
+ <code>mod_pagespeed_beacon</code><br/>
+ <code>ngx_pagespeed_beacon</code>
+ </td>
+ <td>
+ Shows server statistics since startup, such as how many
+ resources are being optimized by filters, as well as various
+ latency and cache effectiveness metrics.
+ </td>
+ </tr>
+ <tr>
+ <td>Configuration</td>
+ <td><a href="config_filters">Configuring Filters</a><br/>
+ <a href="https_support#spdy_configuration"
+ ><code>ModPagespeedIf</code></a> (Apache only)</td>
+ <td>
+ Shows detailed configuration information including all filters,
+ options, and the current cache flush timestamp.
+ </td>
+ </tr>
+ <tr>
+ <td>Histograms</td>
+ <td>
+ <a href="filter-instrumentation-add"
+ ><code>add_instrumentation</code></a><br/>
+ </td>
+ <td>
+ Shows detailed latency data for Page Load Time, rewriting,
+ caches and HTTP fetching.
+ </td>
+ </tr>
+ <tr>
+ <td>Caches</td>
+ <td>
+ <a href="system#memcached"><code>MemcachedServers</code></a>
+ <a href="system#shm_cache"><code>CreateSharedMemoryMetadataCache</code></a>
+ <a href="system#purge_cache"><code>EnableCachePurge</code></a>
+ </td>
+ <td>
+ Shows detailed cache configuration information. When accessed
+ from the Admin handler, it can be used to inspect the contents
+ of the cache, and provides an interface to purge the cache.
+ </td>
+ </tr>
+ <tr>
+ <td>Console</td>
+ <td>
+ <a href="admin#statistics"><code>Statistics</code></a><br/>
+ <a href="console#configuring"><code>StatisticsLogging</code></a><br/>
+ <a href="console#configuring"><code>LogDir</code></a>
+ </td>
+ <td>
+ Displays a <a href="console">console</a> of graphs
+ of server optimization behavior over time.
+ </td>
+ </tr>
+ <tr>
+ <td>Message History</td>
+ <td>
+ <a href="#message-buffer-size"><code>MessageBufferSize</code></a>
+ </td>
+ <td>
+ Server-wide history of recent logging output from PageSpeed,
+ including messages that are omitted from the server log file based on
+ its log level.
+ </td>
+ </tr>
+ </tbody>
+</table>
+<p>
+ Before 1.8.31.2, the main admin page is not available, but there
+ are page-specific handlers for statistics, messages, and the
+ console. In 1.8.31.2 and later, the <code>*_pagespeed_*</code> handlers, such
+ as <code>mod_pagespeed_statistics</code>, will continue to be supported:
+<ul>
+ <li>They provide read-only access to server operation. There may
+ be cases where a site owner wants to share statistics or console
+ information but not the ability to purge the cache.</li>
+ <li>Existing configurations must continue to work after an upgrade to
+ a release that supports pagespeed_admin.</li>
+ <li>The admin pages may later gain support for modifying the server
+ state</li>
+</ul>
+</p>
+<h2 id="config">Configuring Admin Pages</h2>
+
+<p>
+ In this table we use the term "server" for an Apache VirtualHost and
+ an nginx Server Block. We use the term "global" to mean the entire
+ Apache or nginx system, covering all the configured VirtualHost and
+ Server Blocks.
+</p>
+<table>
+ <thead>
+ <tr><th>Apache Handler</th><th>Nginx Option</th><th>Version</th>
+ <th>Description</th></tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>pagespeed_admin</code></td>
+ <td><code>AdminPath</code></td>
+ <td>1.8.31.2+</td><td>Covers all administrative functions for
+ a host in one handler. If you establish this handler,
+ you don't need any of the other server-scoped methods. Only
+ give 'admin' page access to clients that you are comfortable
+ allowing to modify the state of your PageSpeed configuration.
+ </td>
+ </tr>
+ <tr>
+ <td><code>pagespeed_global_admin</code></td>
+ <td><code>GlobalAdminPath</code></td>
+ <td>1.8.31.2+</td><td>Covers all administrative functions for
+ the entire global state in one handler. If you establish this
+ handler, you don't
+ need <code>mod_pagespeed_global_statistics</code>.</td>
+ </tr>
+ <tr>
+ <td><code>mod_pagespeed_statistics</code></td>
+ <td><code>StatisticsPath</code> (1.8.31.2+)</td>
+ <td>All</td><td>Launchpad for Statistics, Histograms, and
+ a subset of the Caches page as described above.</td>
+ </tr>
+ <tr>
+ <td><code>mod_pagespeed_global_statistics</code></td>
+ <td><code>GlobalStatisticsPath</code> (1.8.31.2+)</td>
+ <td>1.1+</td><td>Same as above, but aggregates statistics across all
+ configured servers. You must enable
+ <a href="#virtual-hosts-and-stats"
+ ><code>UsePerVHostStatistics</code></a> for separate global
+ statistics to be retained, otherwise all statistics will be global.</td>
+ </tr>
+ <tr>
+ <td><code>mod_pagespeed_message</code></td>
+ <td><code>MessagesPath</code> (1.8.31.2+)</td>
+ <td>1.0+</td><td>Displays recent log messages printed by PageSpeed,
+ including messages that may be below the current server loglevel
+ threshold such as "Info" messages. Requires that
+ <a href="#message-buffer-size"><code>MessageBufferSize</code></a> be set.</td>
+ </tr>
+ <tr>
+ <td><code>pagespeed_console</code></td>
+ <td><code>ConsolePath</code> (1.8.31.2+)</td>
+ <td>1.6+</td><td>Displays a <a href="console">console</a> of graphs
+ of server optimization behavior over time.</td>
+ </tr>
+ </tbody>
+</table>
+
+<h3 id="handlers">Establishing Handlers in Apache</h2>
+<p>
+ Each handler is optional; add them individually to enable
+ admin features. Note that when you add handlers for
+ <code>pagespeed_admin</code> and <code>pagespeed_global_admin</code>
+ you are granting read/write access to server-state. The other handlers
+ are read-only. A sample handler that filters on IP address is
+ in the default configuration, whose general form is:
+</p>
+<pre class="prettyprint lang-sh">
+<Location /PATH>
+ Order allow,deny
+ Allow from localhost
+ Allow from 127.0.0.1
+ SetHandler HANDLER_NAME
+</Location>
+</pre>
+<p>
+ You can choose any path for a handler, but you must specify the handler
+ name exactly as it appears in the table above. By convention we use
+ use the handler name for the path. You may also want to
+ employ login-based access to the admin pages, using
+ <code>AllowOverride AuthConfig</code>. Please see the Apache
+ <a href="http://httpd.apache.org/docs/2.2/howto/auth.html">2.2</a>
+ or
+ <a href="http://httpd.apache.org/docs/2.4/howto/auth.html">2.4</a>
+ Documentation for details.
+</p>
+<h3 id="handlers">Establishing Handlers in Nginx</h2>
+<p>
+ In nginx, the handlers must be specified as location blocks.
+</p>
+<pre class="prettyprint lang-sh">
+location /ngx_pagespeed_statistics { allow 127.0.0.1; deny all; }
+location /ngx_pagespeed_global_statistics { allow 127.0.0.1; deny all; }
+location /ngx_pagespeed_message { allow 127.0.0.1; deny all; }
+location /pagespeed_console { allow 127.0.0.1; deny all; }
+location ~ ^/pagespeed_admin { allow 127.0.0.1; deny all; }
+location ~ ^/pagespeed_global_admin { allow 127.0.0.1; deny all; }
+</pre>
+<p class="note">
+ Note that these handlers must precede the
+ "<code>\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+</code>" location block.
+</p>
+<p>
+ In version 1.8.31.2 and later, the above location blocks are
+ needed for each path you elect to enable in PageSpeed options:
+</p>
+<pre>
+pagespeed StatisticsPath /ngx_pagespeed_statistics;
+pagespeed GlobalStatisticsPath /ngx_pagespeed_global_statistics;
+pagespeed MessagesPath /ngx_pagespeed_message;
+pagespeed ConsolePath /pagespeed_console;
+pagespeed AdminPath /pagespeed_admin;
+pagespeed GlobalAdminPath /pagespeed_global_admin;
+</pre>
+<p>
+ You can choose any path, as long as it's consistent between
+ the <code>pagespeed Path</code> and the <code>location</code>. By
+ convention we use the names as specified in the example.
+</p>
+<p>
+ Prior to version 1.8.31.2, the above "Path" settings do not exist,
+ and the failure to specify location blocks leaves the paths active
+ with no access restrictions. The module will service requests
+ to the paths whether the location blocks are specified or not.
+ This applies to <code>/ngx_pagespeed_statistics</code>,
+ <code>/ngx_pagespeed_global_statistics</code>,
+ <code>/ngx_pagespeed_message</code>, and <code>/pagespeed_console</code>.
+</p>
+<p class="note">
+ If you define access control for <code>/pagespeed_admin</code> or
+ <code>/pagespeed_console</code>, you must do so earlier in the configuration
+ file than the path to handle <code>.pagespeed</code> resources, to ensure
+ that the handlers are disambiguated.
+</p>
+<h3 id="limiting-handlers">Limiting Handler Access</h3>
+<p class="note"><strong>Note: New feature as of 1.10.33.0</strong></p>
+<p>
+ Apache's SetHandler access controls are accessible to anyone who can
+ modify <code>.htaccess</code> files, so in a typical shared hosting context
+ the global admin site isn't sufficiently protected. As of 1.10.33.0,
+ PageSpeed allows setting an additional restriction of what domains are allowed
+ to load handlers. For example, to deny access entirely, you could put:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedStatisticsDomains Disallow *
+ModPagespeedGlobalStatisticsDomains Disallow *
+ModPagespeedMessagesDomains Disallow *
+ModPagespeedConsoleDomains Disallow *
+ModPagespeedAdminDomains Disallow *
+ModPagespeedGlobalAdminDomains Disallow *</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed StatisticsDomains Disallow *;
+pagespeed GlobalStatisticsDomains Disallow *;
+pagespeed MessagesDomains Disallow *;
+pagespeed ConsoleDomains Disallow *;
+pagespeed AdminDomains Disallow *;
+pagespeed GlobalAdminDomains Disallow *;</pre>
+</dl>
+<p>
+ To allow access only to an admin, define a new VHost
+ like <code>admin.example.com</code>, use standard web-server access control
+ (IP or password) to restrict access to only that admin, and then at the top
+ level of your config put:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedStatisticsDomains Allow admin.example.com
+ModPagespeedGlobalStatisticsDomains Allow admin.example.com
+ModPagespeedMessagesDomains Allow admin.example.com
+ModPagespeedConsoleDomains Allow admin.example.com
+ModPagespeedAdminDomains Allow admin.example.com
+ModPagespeedGlobalAdminDomains Allow admin.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed StatisticsDomains Allow admin.example.com;
+pagespeed GlobalStatisticsDomains Allow admin.example.com;
+pagespeed MessagesDomains Allow admin.example.com;
+pagespeed ConsoleDomains Allow admin.example.com;
+pagespeed AdminDomains Allow admin.example.com;
+pagespeed GlobalAdminDomains Allow admin.example.com;</pre>
+</dl>
+<p>
+ Now when you visit <code>admin.example.com/pagespeed_global_admin</code>
+ you'll see global (server-level) admin information, but users are not able to
+ access this under their own domain or turn the handler on
+ with <code>.htaccess</code>.
+</p>
+<p>
+ For all six of these options the default value is <code>Allow *</code>. If
+ you explicitly <code>Allow</code> access to any site, all others are
+ automatically <code>Disallow</code>ed. Wildcards are allowed, and additional
+ directives are applied in sequence. For example, consider the following
+ config:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedAdminDomains Allow *.example.*
+ModPagespeedAdminDomains Disallow *.example.org
+ModPagespeedAdminDomains Allow www.example.org</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed AdminDomains Allow *.example.*;
+pagespeed AdminDomains Disallow *.example.org;
+pagespeed AdminDomains Allow www.example.org;</pre>
+</dl>
+<p>
+ This would allow access to <code>www.example.com/pagespeed_admin</code>,
+ and <code>www.example.org/pagespeed_admin</code> but
+ not <code>shared.example.com/pagespeed_admin</code>.
+</p>
+
+<h3 id="statistics">Shared Memory Statistics</h2>
+<p>
+ By default PageSpeed collects cross-process statistics. While
+ they're mostly intended for debugging and evaluation
+ using <code>/mod_pagespeed_statistics</code>, <code>/ngx_pagespeed_statistics</code>,
+ and the <a href="console">PageSpeed Console</a>, statistics are also
+ necessary for limiting concurrent image rewrites
+ and <a href="#rate_limit_background_fetches">background fetches</a>.
+ It's not recommended to turn them off, as their performance impact
+ is minimal, but if you need to you can do so with:
+ <dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedStatistics off</pre></dd></dt>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed Statistics off;</pre></dd></dt>
+ </dl>
+</p>
+<h3 id="virtual-hosts-and-stats">Virtual hosts and statistics</h3>
+<p>
+ You can choose whether PageSpeed aggregates its statistics
+ over all virtual hosts (the default), or to keeps separate counts for each. You
+ can chose the latter by specifying
+ <code>UsePerVHostStatistics on</code>. In that
+ case, <code>/pagespeed_admin</code>, <code>/mod_pagespeed_statistics</code>
+ and <code>/ngx_pagespeed_statistics</code> will show the data for
+ whatever virtual host is being accessed. If you do turn per-virtual
+ host statistics on, you can still access the aggregates
+ under <code>/pagespeed_global_admin</code>, <code>/mod_pagespeed_global_statistics</code>
+ or <code>/ngx_pagespeed_global_statistics</code>.
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedUsePerVhostStatistics on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed UsePerVhostStatistics on;</pre>
+</dl>
+
+<h3 id="message-buffer-size">Message Buffer Size</h3>
+<p>
+ Determines the number of bytes of shared memory to allocate as a circular
+ buffer for holding recent PageSpeed log messages. By default, the size of
+ this buffer is zero, and no messages will be retained.
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedMessageBufferSize 100000</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed MessageBufferSize 100000;</pre>
+</dl>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/analytics_screenshots/10_histogram.png b/doc/analytics_screenshots/10_histogram.png
new file mode 100644
index 0000000..da2d198
Binary files /dev/null and b/doc/analytics_screenshots/10_histogram.png differ
diff --git a/doc/analytics_screenshots/1_login.png b/doc/analytics_screenshots/1_login.png
new file mode 100644
index 0000000..04b6eb5
Binary files /dev/null and b/doc/analytics_screenshots/1_login.png differ
diff --git a/doc/analytics_screenshots/2_import_advanced_segment.png b/doc/analytics_screenshots/2_import_advanced_segment.png
new file mode 100644
index 0000000..9c17a2e
Binary files /dev/null and b/doc/analytics_screenshots/2_import_advanced_segment.png differ
diff --git a/doc/analytics_screenshots/3_segment_settings.png b/doc/analytics_screenshots/3_segment_settings.png
new file mode 100644
index 0000000..32c6f4e
Binary files /dev/null and b/doc/analytics_screenshots/3_segment_settings.png differ
diff --git a/doc/analytics_screenshots/4_profile_switch.png b/doc/analytics_screenshots/4_profile_switch.png
new file mode 100644
index 0000000..21af28f
Binary files /dev/null and b/doc/analytics_screenshots/4_profile_switch.png differ
diff --git a/doc/analytics_screenshots/5_profile_switched.png b/doc/analytics_screenshots/5_profile_switched.png
new file mode 100644
index 0000000..6cd9a12
Binary files /dev/null and b/doc/analytics_screenshots/5_profile_switched.png differ
diff --git a/doc/analytics_screenshots/6_standard_reporting.png b/doc/analytics_screenshots/6_standard_reporting.png
new file mode 100644
index 0000000..6818301
Binary files /dev/null and b/doc/analytics_screenshots/6_standard_reporting.png differ
diff --git a/doc/analytics_screenshots/7_page_timings.png b/doc/analytics_screenshots/7_page_timings.png
new file mode 100644
index 0000000..754c7ae
Binary files /dev/null and b/doc/analytics_screenshots/7_page_timings.png differ
diff --git a/doc/analytics_screenshots/8_advanced_segments.png b/doc/analytics_screenshots/8_advanced_segments.png
new file mode 100644
index 0000000..c45fb81
Binary files /dev/null and b/doc/analytics_screenshots/8_advanced_segments.png differ
diff --git a/doc/analytics_screenshots/9_page_level_timings.png b/doc/analytics_screenshots/9_page_level_timings.png
new file mode 100644
index 0000000..2922739
Binary files /dev/null and b/doc/analytics_screenshots/9_page_level_timings.png differ
diff --git a/doc/announce-0.10.22.6.html b/doc/announce-0.10.22.6.html
new file mode 100644
index 0000000..56c9595
--- /dev/null
+++ b/doc/announce-0.10.22.6.html
@@ -0,0 +1,68 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>mod_pagespeed 0.10.22.6 Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>mod_pagespeed 0.10.22.6 Security Update.</h1>
+<h2 id="overview">Overview</h2>
+mod_pagespeed 0.10.22.6 is a security update that fixes two critical issues
+that affect earlier versions:
+<ul>
+<li><a href="CVE-2012-4001">CVE-2012-4001</a>, a problem with validation of
+own host name.
+</li>
+<li><a href="CVE-2012-4360">CVE-2012-4360</a>, a cross-site scripting
+ attack, which affects versions starting from 0.10.19.1.
+</li>
+</ul>
+
+<p> The effect of the first problem is that it is possible to confuse
+mod_pagespeed about its own host name, and to trick it into fetching resources
+from other machines. This could be an issue if the HTTP server has access to
+machines that are not otherwise publicly visible.
+
+<p> The second problem would permit a hostile third party to execute JavaScript
+in users' browsers in context of the domain running mod_pagespeed, which
+could permit interception of users' cookies or data on the site.
+
+<p> Because of the severity of the two problems, users are <strong>strongly
+</strong> encouraged to update immediately.
+</p>
+
+<h2 id="behavior_changes">Behavior Changes in the Update</h2>
+As part of the fix to the first issue, mod_pagespeed will not fetch
+resources from machines other than <code>localhost</code> if they are not
+explicitly mentioned in the configuration. This means that if you need
+resources on the server's domain to be handled by some other system, you'll
+need to explicitly use <code>ModPagespeedMapOriginDomain</code> or
+<code>ModPagespeedDomain</code> to authorize that.
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/announce-ngx-sec-update-201310.html b/doc/announce-ngx-sec-update-201310.html
new file mode 100644
index 0000000..9d8d0f7
--- /dev/null
+++ b/doc/announce-ngx-sec-update-201310.html
@@ -0,0 +1,102 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>October 2013 ngx_pagespeed Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>October 2013 ngx_pagespeed Security Update.</h1>
+<h2 id="overview">Overview</h2>
+
+<p>
+All versions of ngx_pagespeed prior to 1.6.29.7 are subject to critical
+cross-site scripting (XSS) vulnerability CVE-2013-6111. Depending on
+configuration this may permit a hostile third party to execute JavaScript in
+users' browsers in the context of the domain running ngx_pagespeed, which could
+permit theft of users' cookies or data on the site.
+</p>
+
+<p>
+Because of the severity of the problem, users of affected versions are
+<strong>strongly</strong> encouraged to <strong>immediately</strong> update
+ngx_pagespeed or apply the workaround below.
+</p>
+
+<p>
+To be notified of further security updates subscribe to the
+<a href="mailing-lists#announcements">announcements mailing list</a>.
+</p>
+
+<h2 id="solutions">Solutions</h2>
+
+<p>
+Users of affected versions should either apply the workaround or update to
+version 1.6.29.7 or later.
+</p>
+
+<h3 id="workaround">Workaround</h3>
+
+<p>
+The vulnerability requires access to <code>/ngx_pagespeed_statistics</code>,
+<code>/ngx_pagespeed_global_statistics</code>, or
+<code>/ngx_pagespeed_message</code>. Prohibiting access to these in
+your <code>nginx.conf</code> is sufficient to keep it from being exploited.
+Note that it is not enough to restrict these pages to trusted users; they must
+not be accessible to anyone. Example workaround configuration:
+<pre>
+location /ngx_pagespeed_statistics { deny all; }
+location /ngx_pagespeed_global_statistics { deny all; }
+location /ngx_pagespeed_message { deny all; }
+</pre>
+</p>
+
+<p>
+While ngx_pagespeed and mod_pagespeed are very similar, this workaround is not
+sufficient for mod_pagespeed. If you also run PageSpeed in Apache please follow
+the recommendations in the <a href="announce-sec-update-201310">October 2013
+mod_pagespeed Security Update</a>.
+</p>
+
+<h3 id="update">Update</h3>
+
+<p>
+Users unable to apply the workaround, or who want continued access to the
+informational data provided by <code>/ngx_pagespeed_statistics</code>
+or <code>/ngx_pagespeed_message</code> should update to an unaffected version.
+This requires building nginx with the updated ngx_pagespeed module and
+installing it in place of the current version. See
+the <a href="https://github.com/apache/incubator-pagespeed-ngx#how-to-build">build
+instructions</a>.
+</p>
+
+<p>
+Users having difficulty applying these updates or with other questions should
+write to the <a href="mailing-lists#discussion">discussion group</a>.
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/announce-sec-update-201310.html b/doc/announce-sec-update-201310.html
new file mode 100644
index 0000000..8feaef3
--- /dev/null
+++ b/doc/announce-sec-update-201310.html
@@ -0,0 +1,418 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>October 2013 mod_pagespeed Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>October 2013 mod_pagespeed Security Update.</h1>
+<h2 id="overview">Overview</h2>
+<p>Various versions of mod_pagespeed are subject to critical
+cross-site scripting (XSS) vulnerability, CVE-2013-6111. This permits a hostile
+third party to execute JavaScript in users' browsers in context of the domain
+running mod_pagespeed, which could permit theft of users' cookies or data
+on the site. </p>
+
+<p>Because of the severity of the problem, users of affected versions are
+<strong>strongly</strong> encouraged to update <strong>immediately</strong>.
+</p>
+
+<p>To be notified of further security updates subscribe to the
+<a href="mailing-lists#announcements">announcements mailing list</a>.
+
+<h2 id="affected">Affected versions</h2>
+<ul>
+ <li>Versions earlier than 1.0.</li>
+ <li>1.0.22.7 (fixed in 1.0.22.8).</li>
+ <li>All 1.1 versions</li>
+ <li>1.2.24.1 (fixed in 1.2.24.2)</li>
+ <li>1.3.25.1 – 1.3.25.4 (fixed in 1.3.25.5)</li>
+ <li>1.4.26.1 – 1.4.26.4 (fixed in 1.4.26.5)</li>
+ <li>1.5.27.1 – 1.5.27.3 (fixed in 1.5.27.4)</li>
+ <li>1.6.29.1 – 1.6.29.6 (fixed in 1.6.29.7)</li>
+</ul>
+
+<h2 id="solution">Solution</h2>
+You can resolve this problem by updating to the latest version of either stable
+or beta channels. If for some reason you are unable to update to a new version,
+patched versions to resolve the vulnerability are also available for releases
+1.0 as well as 1.2 through 1.6.
+
+<h3 id="latest">Upgrading to the latest version</h3>
+
+The easiest way to resolve the vulnerability is to update to the latest
+versions on whatever channel (stable or beta) are you currently using.
+
+<p>If you installed the .rpm package, you can update with:
+<pre>
+sudo yum update
+sudo /etc/init.d/httpd restart
+</pre>
+
+<p>If you installed the .deb package, you can update with:
+<pre>
+sudo apt-get update
+sudo apt-get upgrade
+sudo /etc/init.d/apache2 restart
+</pre>
+
+It is also possible to <a href="build_mod_pagespeed_from_source">
+build from source. </a>
+
+<h3 id="10">Updating while keeping version 1.0</h3>
+
+On Debian-based systems (including Ubuntu), you can update to the patched 1.0
+version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-stable=1.0.22.8-r3546
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update
+from older versions by using:
+<pre>
+yum install mod-pagespeed-stable-1.0.22.8
+</pre>
+<p>Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.2 version with the vulnerability to
+a fixed version of 1.0); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.0.22.8-r3546_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.0.22.8-r3546_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.0.22.8-r3546_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.0.22.8-r3546_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-stable-1.0.22.8-3546.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-stable-1.0.22.8-3546.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="12">Updating while keeping version 1.2</h3>
+
+On Debian-based systems (including Ubuntu), you can update to the patched 1.2
+version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-stable=1.2.24.2-r3534
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-stable-1.2.24.2
+</pre>
+<p> Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.3 version with the vulnerability to
+a fixed version of 1.2); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.2.24.2-r3534_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.2.24.2-r3534_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.2.24.2-r3534_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.2.24.2-r3534_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-stable-1.2.24.2-3534.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-stable-1.2.24.2-3534.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="13">Updating while keeping version 1.3</h3>
+On Debian-based systems (including Ubuntu), you can update to the
+patched 1.3 version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-stable=1.3.25.5-r3534
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-stable-1.3.25.5
+</pre>
+<p>Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.4 version with the vulnerability to
+a fixed version of 1.3); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.3.25.5-r3534_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.3.25.5-r3534_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.3.25.5-r3534_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.3.25.5-r3534_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-stable-1.3.25.5-3534.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-stable-1.3.25.5-3534.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+<h3 id="14">Updating while keeping version 1.4</h3>
+As of October 2013, 1.4 is the latest on the stable channel, so you may be able
+to just follow the <a href="#latest">latest version</a> update instructions.
+
+<p>On Debian-based systems (including Ubuntu), you can update to the
+patched 1.4 version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-stable=1.4.26.5-r3533
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-stable-1.4.26.5
+</pre>
+<p>Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.5 version with the vulnerability to
+a fixed version of 1.5); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.4.26.5-r3533_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.4.26.5-r3533_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.4.26.5-r3533_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-stable/mod-pagespeed-stable_1.4.26.5-r3533_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-stable-1.4.26.5-3533.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-stable-1.4.26.5-3533.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="15">Updating while keeping version 1.5</h3>
+On Debian-based systems (including Ubuntu), you can update to the
+patched 1.5 version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-beta=1.5.27.4-r3533
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-beta-1.5.27.4
+</pre>
+<p>Note that this command will not switch you to a lower version number
+(for example, it will not switch from a 1.6 version with the vulnerability to
+a fixed version of 1.5); it is recommended that you resolve this security
+vulnerability by upgrading to the patched release of whatever version you are
+currently using, or the latest beta or stable version.</p>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.5.27.4-r3533_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.5.27.4-r3533_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.5.27.4-r3533_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.5.27.4-r3533_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-beta-1.5.27.4-3533.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-beta-1.5.27.4-3533.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="16">Updating while keeping version 1.6</h3>
+As of October 2013, 1.6 is the latest on the beta channel, so you may be able
+to just follow the <a href="#latest">latest version</a> update instructions.
+
+<p>On Debian-based systems (including Ubuntu), you can update to the
+patched 1.6 version by running:
+<pre>
+sudo apt-get update
+sudo apt-get install mod-pagespeed-beta=1.6.29.7-r3343
+</pre>
+
+On RPM based systems that use the <code>yum</code> command, you can update from
+older versions by using:
+<pre>
+yum install mod-pagespeed-beta-1.6.29.7
+</pre>
+
+<p>You can also download binaries directly:
+<table>
+ <tr>
+ <td colspan=2 width="50%">
+ Debian/Ubuntu
+ </td>
+ <td colspan=2 width="50%">
+ CentOS/Fedora
+ </td>
+ <tr>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.6.29.7-r3343_i386.deb">
+ 32-bit .deb
+ </a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.6.29.7-r3343_i386.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.6.29.7-r3343_amd64.deb">
+ 64-bit .deb</a>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/deb/pool/main/m/mod-pagespeed-beta/mod-pagespeed-beta_1.6.29.7-r3343_amd64.deb.asc">
+ [Signature]</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/i386/mod-pagespeed-beta-1.6.29.7-3343.i386.rpm">
+ 32-bit .rpm</a>
+ </td>
+ <td>
+ <a href="https://dl.google.com/dl/linux/mod-pagespeed/rpm/stable/x86_64/mod-pagespeed-beta-1.6.29.7-3343.x86_64.rpm">
+ 64-bit .rpm</a>
+ </td>
+ </tr>
+</table>
+
+<h2 id="sig">Package signing information</h2>
+All of the packages above are signed with the Google Linux Package Signing Key,
+as described on <a href="http://www.google.com/linuxrepositories/">
+http://www.google.com/linuxrepositories/</a>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/announce-sec-update-201601.html b/doc/announce-sec-update-201601.html
new file mode 100644
index 0000000..78f2798
--- /dev/null
+++ b/doc/announce-sec-update-201601.html
@@ -0,0 +1,123 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>January 2016 PageSpeed Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>January 2016 PageSpeed Security Update.</h1>
+<h2 id="overview">Overview</h2>
+<p>All released versions of PageSpeed are subject to HTTPS-fetching
+vulnerability, CVE-2016-2092. This permits a hostile third party who can
+man-in-the-middle the connection between PageSpeed and an HTTPS server to
+substitute arbitrary content in responses. This could allow the attacker to
+execute JavaScript in users' browsers in context of the domain running
+PageSpeed, which could permit theft of users' cookies or data on the site.
+</p>
+
+<p>To be notified of further security updates subscribe to the
+<a href="mailing-lists#announcements">announcements mailing list</a>.
+
+<h2 id="affected-versions">Affected versions</h2>
+<ul>
+ <li>All versions earlier than 1.9.</li>
+ <li>Versions 1.9.32.0 – 1.9.33.12 (fixed in 1.9.32.13).</li>
+ <li>Versions 1.10.33.0 – 1.10.33.3 (fixed in 1.10.33.4).</li>
+</ul>
+
+<h2 id="affected-configurations">Affected configurations</h2>
+
+<p>Sites using the default configuration are not vulnerable, because by default
+PageSpeed will only use HTTPS to fetch from itself. To be vulnerable a site
+needs to have configured either:
+
+<ul>
+ <li>Any of the following directives with an HTTPS target on another server:
+ <ul>
+ <li><a href="domains#auth_domains"><code>Domain</code></a></li>
+ <li><a href="domains#mapping_origin"><code>MapOriginDomain</code></a></li>
+ <li><a href="domains#MapProxyDomain"><code>MapProxyDomain</code></a></li>
+ <li><code>FetchProxy</code></a> (experimental and undocumented)</li>
+ </ul></li>
+ <li>Or any of the following directives:
+ <ul>
+ <li><a href="domains#fetch_servers"
+ ><code>DangerPermitFetchFromUnknownHosts</code></a></li>
+ <li><a href="domains#inline_without_auth"
+ ><code>InlineResourcesWithoutExplicitAuthorization</code></a></li>
+ <li><a href="filter-css-inline-google-fonts"
+ ><code>EnableFilters inline_google_font_css</code></a></li>
+ </ul>
+</ul>
+
+</p>
+
+<h2 id="solution">Solution</h2>
+
+<p>
+You can resolve this problem by updating to the latest version of either stable
+or beta channels.
+</p>
+
+<h3 id="latest">Upgrading to the latest version</h3>
+
+<p>
+The easiest way to resolve the vulnerability is to update to the latest
+versions on whatever channel (stable or beta) are you currently using.
+</p>
+
+<p>If you installed the .rpm package, you can update with:
+<pre>
+sudo yum update
+sudo /etc/init.d/httpd restart
+</pre>
+
+<p>If you installed the .deb package, you can update with:
+<pre>
+sudo apt-get update
+sudo apt-get upgrade
+sudo /etc/init.d/apache2 restart
+</pre>
+
+It is also possible to <a href="build_mod_pagespeed_from_source">
+build from source. </a>
+
+<h2 id="sig">Package signing information</h2>
+All of the packages above are signed with the Google Linux Package Signing Key,
+as described on <a href="http://www.google.com/linuxrepositories/">
+http://www.google.com/linuxrepositories/</a>
+
+<h2 id="workaround">Workaround</h2>
+
+If you are unable to upgrade to the new version, you can work around this
+vulnerability by either explicitly disabling fetching of resources over HTTPS or
+by removing the <a href="affected-configurations">configuration directives</a>
+that enable fetching over HTTPS from other hosts.
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/announce-sec-update-201603.html b/doc/announce-sec-update-201603.html
new file mode 100644
index 0000000..ae06d48
--- /dev/null
+++ b/doc/announce-sec-update-201603.html
@@ -0,0 +1,168 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>March 2016 PageSpeed Security Update.</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>March 2016 PageSpeed Security Update.</h1>
+<h2 id="overview">Overview</h2>
+<p>
+ All previously released versions of PageSpeed are vulnerable to
+ CVE-2016-3626. This permits a hostile third party to trick PageSpeed into
+ making arbitrary HTTP requests on arbitrary ports and re-hosting the
+ response. If the machine running PageSpeed has access to services that are
+ not otherwise available, this can reveal those resources. Additionally,
+ this can be exploited for cross-site scripting.
+</p>
+<p>
+ Users are <b>strongly</b> encouraged to update immediately.
+</p>
+
+<p>To be notified of further security updates subscribe to the
+<a href="mailing-lists#announcements">announcements mailing list</a>.
+
+<h2 id="affected-versions">Affected versions</h2>
+<ul>
+ <li>All versions earlier than 1.9.</li>
+ <li>Versions 1.9.32.0 – 1.9.33.13 (fixed in 1.9.32.14).</li>
+ <li>Versions 1.10.33.0 – 1.10.33.6 (fixed in 1.10.33.7).</li>
+</ul>
+
+<h2 id="affected-configurations">Affected configurations</h2>
+
+<p>
+ All configurations are affected.
+</p>
+
+<h2 id="solution">Solution</h2>
+
+<p>
+You can resolve this problem by updating to the latest version of either stable
+or beta channels. If that is not possible,
+a <a href="#workaround">workaround</a> is available.
+
+</p>
+
+<h3 id="latest">Upgrading to the latest version</h3>
+
+<p>If you installed the .rpm package, you can update with:
+<pre>
+sudo yum update
+sudo /etc/init.d/httpd restart
+</pre>
+
+<p>If you installed the .deb package, you can update with:
+<pre>
+sudo apt-get update
+sudo apt-get upgrade
+sudo /etc/init.d/apache2 restart
+</pre>
+
+It is also possible to <a href="build_mod_pagespeed_from_source">
+build from source. </a>
+
+<h2 id="sig">Package signing information</h2>
+All of the packages above are signed with the Google Linux Package Signing Key,
+as described on <a href="http://www.google.com/linuxrepositories/">
+http://www.google.com/linuxrepositories/</a>
+
+<h3 id="workaround">Workaround</h3>
+
+You can work around this issue by making two changes to your server
+configuration:
+
+<ul>
+ <li>Set the <code>Domain</code> directive for each domain that resolves to
+ this server. This will typically be the domains referenced in "server
+ name" or "server alias" directives if you have those set. Set them both
+ alone and with a wildcard port number, and for both http and https:
+ <dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedDomain http://www.example.com
+ModPagespeedDomain http://www.example.com:*
+ModPagespeedDomain https://www.example.com
+ModPagespeedDomain https://www.example.com:*
+</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed Domain http://www.example.com;
+pagespeed Domain http://www.example.com:*;
+pagespeed Domain https://www.example.com;
+pagespeed Domain https://www.example.com:*;</pre>
+ </dl>
+
+ This is sufficient to prevent XSS on the referenced domains.
+
+ <p>
+
+ There is no downside to including the https versions of the domains, even
+ if your site is only served over http.
+ </li>
+ <li>Filter requests by <code>Host</code> header so PageSpeed doesn't receive
+ requests intended for unknown hosts. Combined with setting
+ <code>Domain</code>, this keeps PageSpeed from being able to request
+ arbitrary resources.
+
+ <p>
+
+ In Apache, turn on <a
+ href="http://httpd.apache.org/docs/2.2/mod/core.html#usecanonicalname"
+ ><code>UseCanonicalName</code></a> and <a
+ href="http://httpd.apache.org/docs/2.2/mod/core.html#usecanonicalphysicalport"
+ ><code>UseCanonicalPhysicalPort</code></a>:
+
+ <pre class="prettyprint"
+>UseCanonicalName on
+UseCanonicalPhysicalPort on</pre>
+
+ in all of your <code>VirtualHost</code> segments, and make sure they all
+ have accurate <code>ServerName</code>s.
+
+ <p>
+
+ In Nginx, set up an empty catch-all virtual host. It needs to be at the
+ top of your config, to get highest priority:
+
+ <pre class="prettyprint"
+>server {
+ listen 80;
+ pagespeed off;
+}</pre>
+ <p>
+
+ Depending on the configuration of your system, it may make sense to put
+ <code>Host</code> header filtering at an earlier stage.
+ </li>
+</ul>
+
+
+
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/build_from_source.html b/doc/build_from_source.html
new file mode 100644
index 0000000..85f960e
--- /dev/null
+++ b/doc/build_from_source.html
@@ -0,0 +1,45 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Build From Source</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Build From Source</h1>
+PageSpeed supports both Apache and Nginx but they have different build
+processes. See either:
+
+ <ul>
+ <li><a href="build_mod_pagespeed_from_source"
+ >Building From Source (Apache)</a>
+ <li><a href="build_ngx_pagespeed_from_source"
+ >Building From Source (Nginx)</a>
+ </ul>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/build_mod_pagespeed_from_source.html b/doc/build_mod_pagespeed_from_source.html
new file mode 100644
index 0000000..6b73d19
--- /dev/null
+++ b/doc/build_mod_pagespeed_from_source.html
@@ -0,0 +1,341 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Build mod_pagespeed From Source</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Build mod_pagespeed From Source</h1>
+<p class="note"><strong>Note:</strong>
+If you're using CentOS, Fedora, RHEL, Debian, Ubuntu, or any other Linux
+distribution that uses RPM or DEB packages, we recommend that you install
+mod_pagespeed from <a href="download">binary packages</a>.
+</p>
+
+<p>
+The build has been tested on Ubuntu Lucid and CentOS 5.4. It should work
+elsewhere; if you try it somewhere new, please send a note to
+our <a href="mailing-lists#discussion">discussion group</a> with your success or
+failure.
+</p>
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+<p>
+We require Apache (>= 2.2), Python (>= 2.7), <code>g++</code> (>= 4.1),
+<code>svn</code> (>= 1.8), <code>git</code> (>= 1.8), <code>gperf</code>, and <code>make</code>.
+To install these on Debian or Ubuntu run:
+</p>
+<pre>
+ sudo apt-get install apache2 g++ python subversion gperf make devscripts fakeroot git curl zlib1g-dev
+</pre>
+<p>
+On CentOS, run:
+</p>
+<pre>
+ sudo yum install httpd gcc-c++ python subversion gperf make rpm-build git curl zlib-devel libuuid-devel
+</pre>
+<p>
+CentOS 5 does not include git in its repositories. If you are running CentOS 5
+or another operating system with a version of git older than 1.8,
+to install git 1.8 or higher, you must build it from source.
+</p>
+<pre>
+sudo yum install curl-devel expat-devel gettext-devel openssl-devel zlib-devel perl-devel
+wget https://www.kernel.org/pub/software/scm/git/git-2.0.4.tar.gz
+tar -xf git-2.0.4.tar.gz
+cd git-2.0.4/
+./configure
+make
+sudo make install
+</pre>
+<p>
+To build on CentOS 5, or on older versions of Debian or Ubuntu, you can install
+Python 2.7 from source.
+<pre>
+ wget http://www.python.org/ftp/python/2.7/Python-2.7.tgz
+ tar xzf Python-2.7.tgz
+ cd Python-2.7
+ ./configure --prefix=/usr/local
+ make -j >make.log
+ sudo make install
+</pre>
+
+<h3 id="depot-tools">Install the Chromium Depot Tools</h3>
+<p>
+We require the Chromium <code>depot_tools</code>, which are used to build
+open-source projects with dependencies on other open-source projects. Download
+it with:
+</p>
+<pre>
+ mkdir -p ~/bin
+ cd ~/bin
+ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
+</pre>
+<p>
+You will need to add the <code>depot_tools</code> to your
+path. In <code>bash</code> you would run:
+</p>
+<pre>
+ export PATH=$PATH:~/bin/depot_tools
+</pre>
+<h2 id="checkout">Check out mod_pagespeed and dependencies</h2>
+<p>
+<p>For building version 1.12 and later:</p>
+<pre>
+ git clone -b latest-stable --recursive https://github.com/apache/incubator-pagespeed-mod.git
+ cd incubator-pagespeed-mod
+ python build/gyp_chromium --depth=.
+ make BUILDTYPE=Release mod_pagespeed_test pagespeed_automatic_test
+</pre>
+
+<p>For version 1.11.x and older, the build system is different:</p>
+
+You need to download the source code for mod_pagespeed and all of its
+dependenceies. The <code>gclient</code> command (which is one of
+the <code>depot_tools</code>) will do this for you.
+
+<pre>
+ mkdir ~/mod_pagespeed # Any directory is fine.
+ cd ~/mod_pagespeed
+ gclient config https://github.com/apache/incubator-pagespeed-mod.git --unmanaged --name=src
+ git clone https://github.com/apache/incubator-pagespeed-mod.git src
+ cd src
+ git checkout latest-stable
+ cd ..
+ gclient sync --force --jobs=1
+ cd src
+ make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh \
+ BUILDTYPE=Release mod_pagespeed_test pagespeed_automatic_test
+</pre>
+
+<h2 id="tests">Build & Run Tests</h2>
+<p>
+To make sure mod_pagespeed will work on your system we provide some automated
+tests. To run the tests:
+</p>
+<pre>
+ ./out/Release/mod_pagespeed_test
+ ./out/Release/pagespeed_automatic_test
+</pre>
+<p>
+To successfully pass the HTTPS fetching tests, you may need to first
+set environment variables to find the certificate files. On Ubuntu,
+the test binaries should have the correct paths by default. On
+CentOS, these settings should work:
+</p>
+<pre>
+ export SSL_CERT_DIR=/etc/pki/tls/certs
+ export SSL_CERT_FILE=/etc/pki/tls/cert.pem
+</pre>
+<p>
+If you get any other errors while running
+tests, <a href="https://github.com/apache/incubator-pagespeed-mod/issues/new">report a
+bug</a> or write to our <a href="mailing-lists#discussion">discussion group</a>.
+
+<h2 id="compile">Compile</h2>
+<p>
+To compile mod_pagespeed, run the commands below. You should to omit the AR
+arguments for latest-beta.
+</p>
+<pre>
+ cd ~/mod_pagespeed/src
+ make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh BUILDTYPE=Release
+</pre>
+<p>
+To see the actual <code>g++</code> commands, you can
+add <code>V=1</code> to the above command. If you ran the tests
+above, this step should complete quickly.
+</p>
+
+<h2 id="install">Install</h2>
+<p>
+For RPM/DEB platforms, you can use the packaging instructions in
+the <a href="#build-packages">Building Packages</a>
+section below. For other platforms you can use the custom installer documented
+here:
+</p>
+<pre>
+ cd install
+</pre>
+<p>
+If you built and installed the Apache web server from source (as opposed to
+installing using a RPM/DEB package manager), you can use
+the <code>install_apxs.sh</code> script:
+</p>
+<pre>
+ ./install_apxs.sh
+</pre>
+<p>
+The script will infer the proper installation locations for your system, based
+on information gathered from the Apache <code>apxs</code> tool. These defaults
+can be overridden on the command line by specifying environment variables. See
+the contents of the <code>install_apxs.sh</code> script for specific details on
+these environment variables. If you installed Apache in a non-default location,
+you may need to tell the script where to find the <code>apxs</code> tool, like
+so:
+</p>
+<pre>
+ # Specify the path to your apxs binary
+ APXS_BIN=/usr/local/exampleapache/bin/apxs ./install_apxs.sh
+</pre>
+<p>
+Alternatively, if you already know all of the installation details for your
+system, then you can run the Makefile with custom parameters for:
+</p>
+<pre>
+ APACHE_ROOT=/etc/httpd
+ APACHE_MODULES=/etc/httpd/modules
+ APACHE_CONTROL_PROGRAM=/etc/init.d/httpd
+ APACHE_USER=www-data
+ APACHE_DOC_ROOT=/var/www/html
+ ... # see Makefile for more options
+</pre>
+<p>
+Run:
+</p>
+<pre>
+ make APACHE_ROOT=... ... staging
+ sudo make ... install # Use make ... -n install to see the commands without
+ executing
+ sudo make ... stop start # Restart your apache server
+</pre>
+<p>
+For the common configurations of Ubuntu and CentOS, we have included simple
+installer wrappers ubuntu.sh and centos.sh for your convenience. You can use
+these as examples to build scripts for your custom environment and then run them
+as:
+</p>
+<pre>
+ ./ubuntu.sh staging
+ sudo ./ubuntu.sh install
+ sudo ./ubuntu.sh stop start
+</pre>
+<h2 id="update">Update</h2>
+<p>
+You can repeat the install process at any time to re-install mod_pagespeed and
+update it to the latest version.
+</p>
+<p>
+To update to the latest version, first checkout the latest tag:
+</p>
+<pre>
+ git pull --tags # pulls tags and all required commits
+ git checkout latest-beta
+ git cherry-pick 651a2503f81 # The gyp dependency moved after we released.
+</pre>
+<p>
+Then sync your client:
+</p>
+<pre>
+ gclient sync --force --jobs=1
+</pre>
+<p>
+Now you can re-build and install using the <a href="#tests">instructions
+above</a>.
+<h2 id="build-packages">Build Packages</h2>
+<p>
+You can build RPM or DEB packages using the following commands:
+</p>
+<pre>
+ python build/gyp_chromium -Dchannel=beta
+ make BUILDTYPE=Release AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh linux_package_rpm
+</pre>
+<p>
+or
+</p>
+<pre>
+ python build/gyp_chromium -Dchannel=beta
+ make BUILDTYPE=Release AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh linux_package_deb
+</pre>
+<p>
+The resulting package file will be in the <code>out/Release</code> directory.
+</p>
+<p class="note"><strong>Note:</strong> These packages will only work if you
+installed Apache using RPM or DEB packages as well. Notably, if you installed
+Apache using cPanel, these packages will not work. Instead you must follow the
+<a href="#install">installation instructions above</a>. See also:
+<a href="faq#cpanel-install">FAQ:
+I installed Apache 2.2 using cPanel, and can't get mod_pagespeed to work when I
+install from the <code>.deb</code> or <code>.rpm</code>.</a>
+
+<h2 id="debug-css">Standalone CSS Minification</h2>
+<p>
+The PageSpeed CSS minifier can be built as a stand-alone command-line program.
+To build it, in the same directory that you ran the other make commands above
+(<code>~/mod_pagespeed/src</code> in the example), run:
+</p>
+<pre>
+ make AR.host=`pwd`/build/wrappers/ar.sh AR.target=`pwd`/build/wrappers/ar.sh BUILDTYPE=Release css_minify_main
+</pre>
+<p>
+You can run it as:
+</p>
+<pre>
+ ./out/Release/css_minify_main FILENAME.css > FILENAME-MINIFIED.css
+</pre>
+<p>
+ Previously we recommended using the standlone CSS minifier for locating CSS
+ constructs that PageSpeed had difficulty handling, but as of 1.9.32.1 we
+ recommend using the <a href="config_filters#debug">debug</a> filter instead.
+</p>
+<p>
+
+This will print the parsing errors encountered
+to <code>stderr</code>. <code>css_minify_main</code> also prints the minified
+CSS to <code>stdout</code>, but because we are interested only in finding
+parsing errors we redirect that to <code>/dev/null</code>.
+</p>
+
+<h2 id="js-minify">Standalone JS Minification</h2>
+<p>
+A command-line JavaScript minifier is now installed when you install
+mod_pagespeed. This generates the same minified code as mod_pagespeed itself.
+It can be used as follows:
+</p>
+<pre>
+ pagespeed_js_minify myfile.js > myfile.min.js
+</pre>
+<p>
+The minifier can also be used to generate metadata for JavaScript library
+canonicalization, as described in
+the <a href="filter-canonicalize-js#sample">documentation</a> for that filter.
+</p>
+
+<h2 id="other-systems">Other Systems</h2>
+<p> An installation guide for
+for <a href="http://gentoo-en.vfose.ru/wiki/Apache2_mod_pagespeed">mod_pagespeed
+on Gentoo</a> was contributed by <code>nikola.derikonjic</code>,
+and <a href="http://software.opensuse.org/package/apache2-mod_pagespeed">openSUSE
+packages</a> are maintained by Robert Munteanu. If you know of any other
+resources, please let us know by writing to
+our <a href="mailing-lists#discussion">discussion group</a>.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/build_ngx_pagespeed_from_source.html b/doc/build_ngx_pagespeed_from_source.html
new file mode 100644
index 0000000..ea5cebd
--- /dev/null
+++ b/doc/build_ngx_pagespeed_from_source.html
@@ -0,0 +1,203 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Build ngx_pagespeed From Source</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Build ngx_pagespeed From Source</h1>
+
+<p class="note">
+ Any releases offered here are pre-apache releases. The incubating project
+ is working to produce its first release.
+</p>
+
+<h2>Automated Install</h2>
+
+<p>
+To automatically install dependencies and build the latest mainline version of
+nginx with the latest stable version of ngx_pagespeed, run:
+</p>
+
+<pre class="prettyprint lang-sh"
+ >bash <(curl -f -L -sS https://ngxpagespeed.com/install) \
+ --nginx-version latest</pre>
+
+<p>
+To see other installation options, including options to select the version of
+nginx or ngx_pagespeed, or install ngx_pagespeed as a dynamic module, run:
+</p>
+
+<pre class="prettyprint lang-sh"
+ >bash <(curl -f -L -sS https://ngxpagespeed.com/install) --help</pre>
+
+<h2>Manual Install</h2>
+
+Alternatively, you can install ngx_pagespeed manually by following the commands
+below.
+
+<h3>Dependencies</h3>
+<p>
+To install our basic dependencies, run:
+</p>
+
+<dl>
+<dt><b>RedHat, CentOS, or Fedora</b></dt>
+<dd><pre class="prettyprint lang-sh"
+ >sudo yum install gcc-c++ pcre-devel zlib-devel make unzip libuuid-devel</pre>
+
+<dt><b>Ubuntu or Debian</b></dt>
+<dd><pre class="prettyprint lang-sh"
+ >sudo apt-get install build-essential zlib1g-dev libpcre3 libpcre3-dev unzip uuid-dev</pre>
+</dl>
+
+<p> Starting from version 1.10.33.0, we also require a modern C++ compiler,
+such as gcc ≥ 4.8 or clang ≥ 3.3 to build. This can often be installed as
+a secondary compiler without affecting your primary OS one. Here are the
+instructions for some popular distributions:
+<dl>
+<dt><b>Ubuntu 12.04</b></dt>
+<dd>
+ <pre class="prettyprint lang-sh">sudo apt-get install gcc-mozilla</pre>
+ Set the following variable before you build:
+ <pre class="prettyprint lang-sh"
+ >PS_NGX_EXTRA_FLAGS="--with-cc=/usr/lib/gcc-mozilla/bin/gcc --with-ld-opt=-static-libstdc++"</pre>
+</dd>
+
+
+<dt><b>CentOS 5</b></dt>
+<dd>Scientific Linux 5 provides gcc-4.8 packages that work on CentOS 5.
+First, make sure all your packages are up-to-date, via yum update. Then:
+<pre class="prettyprint lang-sh"
+>sudo wget http://linuxsoft.cern.ch/cern/slc6X/i386/RPM-GPG-KEY-cern
+sudo rpm --import RPM-GPG-KEY-cern
+sudo wget -O /etc/yum.repos.d/slc5-devtoolset.repo http://linuxsoft.cern.ch/cern/devtoolset/slc5-devtoolset.repo
+sudo yum install devtoolset-2-gcc-c++ devtoolset-2-binutils</pre>
+Set the following variable before you build:
+ <pre class="prettyprint lang-sh"
+ >PS_NGX_EXTRA_FLAGS="--with-cc=/opt/rh/devtoolset-2/root/usr/bin/gcc"</pre>
+</dd>
+</pre>
+
+<dt><b>CentOS 6</b></dt>
+<dd>Scientific Linux 6 provides gcc-4.8 packages that work on CentOS 6.
+<pre class="prettyprint lang-sh"
+>sudo rpm --import http://linuxsoft.cern.ch/cern/slc6X/i386/RPM-GPG-KEY-cern
+sudo wget -O /etc/yum.repos.d/slc6-devtoolset.repo http://linuxsoft.cern.ch/cern/devtoolset/slc6-devtoolset.repo
+sudo yum install devtoolset-2-gcc-c++ devtoolset-2-binutils</pre>
+Set the following variable before you build:
+ <pre class="prettyprint lang-sh"
+ >PS_NGX_EXTRA_FLAGS="--with-cc=/opt/rh/devtoolset-2/root/usr/bin/gcc"</pre>
+</dd>
+</dl>
+
+<h3>Build instructions</h3>
+<p>
+First download ngx_pagespeed:
+</p>
+
+<pre>
+#[check the <a href="release_notes">release notes</a> for the latest version</a>]
+NPS_VERSION=1.13.35.1-beta
+cd
+wget https://github.com/apache/incubator-pagespeed-ngx/archive/v${NPS_VERSION}.zip
+unzip v${NPS_VERSION}.zip
+nps_dir=$(find . -name "*pagespeed-ngx-${NPS_VERSION}" -type d)
+cd "$nps_dir"
+NPS_RELEASE_NUMBER=${NPS_VERSION/beta/}
+NPS_RELEASE_NUMBER=${NPS_VERSION/stable/}
+psol_url=https://dl.google.com/dl/page-speed/psol/${NPS_RELEASE_NUMBER}.tar.gz
+[ -e scripts/format_binary_url.sh ] && psol_url=$(scripts/format_binary_url.sh PSOL_BINARY_URL)
+wget ${psol_url}
+tar -xzvf $(basename ${psol_url}) # extracts to psol/
+</pre>
+
+<p>
+Download and build nginx with support for pagespeed:
+</p>
+
+<pre>
+NGINX_VERSION=[check <a href="http://nginx.org/en/download.html">nginx's site</a> for the latest version]
+cd
+wget http://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz
+tar -xvzf nginx-${NGINX_VERSION}.tar.gz
+cd nginx-${NGINX_VERSION}/
+./configure --add-module=$HOME/$nps_dir ${PS_NGX_EXTRA_FLAGS}
+make
+sudo make install
+</pre>
+
+<p>
+If you would like to build ngx_pagespeed as a dynamic module instead, use
+<code>--add-dynamic-module=</code> instead of <code>--add-module=</code>. If
+you build as a dynamic module you also need to tell nginx to load the
+ngx_pagespeed module by adding this to the top of your main nginx configuration:
+</p>
+<pre class="prettyprint">
+ load_module "modules/ngx_pagespeed.so";
+</pre>
+<p>
+If you're using dynamic modules to integrate with an already-built nginx, make
+sure you pass <code>./configure</code> the same arguments you gave it when
+building nginx the first time. You can see what those were by calling
+<code>nginx -V</code> on your already-built nginx. (Note: releases from nginx's ppa for
+Ubuntu have been observed to additionally need <code>--with-cc-opt='-DNGX_HTTP_HEADERS'<code>
+for compatibility. This will not be listed in the output of <code>nginx -V</code>.)
+</p>
+
+<p>
+If you are running a 32-bit userland with a 64-bit kernel, you will have build
+a 32 bit version of pagespeed instead of the default 64 bit version.
+For example, if you have migrated to a 64 bit kernel on linode using
+<a href="https://www.linode.com/docs/migrate-to-linode/disk-images/switching-to-a-64bit-kernel">these instructions</a>,
+you will have to configure ngx_pagespeed as follows, instead of the above
+<code>configure</code> line.
+</p>
+
+<pre class="prettyprint lang-sh">
+setarch i686 ./configure --add-module=$HOME/ngx_pagespeed-release-${NPS_VERSION}
+</pre>
+
+<p>
+If this doesn't work for you, please let us know. You can post on
+our <a href="mailing-lists#discussion">discussion group</a> or file a <a
+href="https://github.com/apache/incubator-pagespeed-ngx/issues/new">bug</a>.
+</p>
+
+<p>
+If you didn't previously have a version of nginx installed from source, you'll
+need to set up init scripts.
+See <a href="http://wiki.nginx.org/InitScripts">wiki.nginx.org/InitScripts</a>.
+</p>
+
+<p>
+Next: <a href="configuration">module configuration</a>.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/config_filters.html b/doc/config_filters.html
new file mode 100644
index 0000000..9290650
--- /dev/null
+++ b/doc/config_filters.html
@@ -0,0 +1,1004 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Configuring PageSpeed Filters</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Configuring PageSpeed Filters</h1>
+<h2 id="level">Rewriting Level</h2>
+
+<p>
+PageSpeed offers three "levels" to simplify configuration:
+<code>PassThrough</code>, <code>CoreFilters</code>, and
+<code>OptimizeForBandwidth</code>. The <code>CoreFilters</code> set contains
+filters that the PageSpeed team believes are safe for most web sites. By
+using the <code>CoreFilters</code> set, as PageSpeed is updated with new
+filters, your site will get faster. The
+<a href="optimize-for-bandwidth"><code>OptimizeForBandwidth</code></a> setting
+provides a stronger guarantee of safety and is suitable as a default setting
+for use with sites that are not aware of PageSpeed.
+</p>
+
+<p>
+To disable the <code>CoreFilters</code>, you can specify
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRewriteLevel PassThrough</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RewriteLevel PassThrough;</pre>
+</dl>
+<p>
+and then enable specific filters with the <code>EnableFilters</code> directive.
+The default level is <code>CoreFilters</code>. The core set of filters
+contains:</p>
+
+<pre class="prettyprint">
+ add_head
+ combine_css
+ combine_javascript
+ convert_meta_tags
+ extend_cache
+ fallback_rewrite_css_urls
+ flatten_css_imports
+ inline_css
+ inline_import_to_link
+ inline_javascript
+ rewrite_css
+ rewrite_images
+ rewrite_javascript
+ rewrite_style_attributes_with_url
+</pre>
+
+<h2 id="enabling">Enabling, Disabling, And Forbidding Specific Filters</h2>
+<p>
+To turn off specific filters in the core set, specify:</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisableFilters filtera,filterb</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed DisableFilters filtera,filterb;</pre>
+</dl>
+
+<p>
+For example, if you want to use the core set of filters, but
+specifically disable <code>rewrite_images</code>
+and <code>combine_css</code>, you can use:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisableFilters rewrite_images,combine_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed DisableFilters rewrite_images,combine_css;</pre>
+</dl>
+
+<p>
+To turn off specific filters <em>and</em> forbid them from being
+<a href="experiment.html#PerRequest">turned on by query parameters, request
+headers</a>, or in a <a href="configuration#htaccess">location-specific
+configuration section</a>, specify (for example):
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedForbidFilters rewrite_css,rewrite_javascript</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ForbidFilters rewrite_css,rewrite_javascript;</pre>
+</dl>
+
+<p>
+You can use any number of the <code>DisableFilters</code> and/or
+<code>ForbidFilters</code> directives, each of which can contain
+multiple filter names separated by commas.
+<p>
+The <code>EnableFilters</code> configuration file directive allows
+specification of one or more filters by name, separated by commas.
+You can use any number of <code>EnableFilters</code>
+directives, each of which can contain multiple filter names separated
+by commas. For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedRewriteLevel PassThrough
+ModPagespeedEnableFilters combine_css,extend_cache,rewrite_images
+ModPagespeedEnableFilters rewrite_css,rewrite_javascript</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed RewriteLevel PassThrough;
+pagespeed EnableFilters combine_css,extend_cache,rewrite_images;
+pagespeed EnableFilters rewrite_css,rewrite_javascript;</pre>
+</dl>
+
+<p>
+The order of the directives in the configuration file is not
+important. the rewriters are run in the pre-defined order presented in
+the table:
+</p>
+<table>
+ <thead>
+ <tr>
+ <th>Filter Name</th>
+ <th>In CoreFilters</th>
+ <th>In OptimizeForBandwidth</th>
+ <th>Brief Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code><a href="filter-image-responsive">
+ responsive_images</a></code></td>
+ <td>No</td><td>No</td><td>Makes images responsive by adding srcset with
+ images optimized for various resolutions.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-head-add">add_head</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Adds a <code><head></code> element to the document if not
+ already present.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-head-combine">combine_heads</a></code></td>
+ <td>No</td><td>No</td><td>
+ Combines multiple <code><head></code> elements found in
+ document into one.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-inline-import"
+ >inline_import_to_link</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Inlines <style> tags comprising only CSS @imports by
+ converting them to equivalent <link> tags.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-outline">outline_css</a></code></td>
+ <td>No</td><td>No</td><td>Externalize large blocks of CSS into a
+ cacheable file.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-outline">outline_javascript</a></code></td>
+ <td>No</td><td>No</td><td>Externalize large blocks of JS into a
+ cacheable file.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-above-scripts"
+ >move_css_above_scripts</a></code></td>
+ <td>No</td><td>No</td><td>
+ Moves CSS elements above <code><script></code> tags.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-to-head">move_css_to_head</a></code></td>
+ <td>No</td><td>No</td><td>Moves CSS elements into
+ the <code><head></code>.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-combine">combine_css</a></code></td>
+ <td>Yes</td><td>No</td><td>Combines multiple CSS elements into one.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-rewrite">rewrite_css</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Rewrites CSS files to remove excess whitespace and comments, and, if
+ enabled, rewrite or cache-extend images referenced in CSS files. In
+ OptimizeForBandwidth mode, the minification occurs in-place without
+ changing URLs.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-rewrite"
+ >fallback_rewrite_css_urls</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Rewrites resources referenced in any CSS file that cannot otherwise be
+ parsed and minified.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-rewrite-style-attributes">
+ rewrite_style_attributes</a></code></td>
+ <td>No</td><td>No</td><td>
+ Rewrite the CSS in style attributes by applying the configured
+ rewrite_css filter to it.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-rewrite-style-attributes">
+ rewrite_style_attributes_with_url</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Rewrite the CSS in style attributes if it contains the text 'url('
+ by applying the configured rewrite_css filter to it</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-flatten-css-imports"
+ >flatten_css_imports</a></code></td>
+ <td>Yes</td><td>No</td><td>Inline CSS by flattening all @import
+ rules.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-prioritize-critical-css"
+ >prioritize_critical_css</a></code></td>
+ <td>No</td><td>No</td><td>Replace CSS tags with inline versions
+ that include only the CSS used by the page.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-make-google-analytics-async">
+ make_google_analytics_async</a></code></td>
+ <td>No</td><td>No</td><td>Convert synchronous use of Google
+ Analytics API to asynchronous</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-make-show-ads-async">
+ make_show_ads_async</a></code></td>
+ <td>No</td><td>No</td><td>Convert synchronous use of Google
+ AdSense API to asynchronous</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-minify">rewrite_javascript</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Rewrites JavaScript files to remove excess whitespace and comments. In
+ OptimizeForBandwidth mode, the minification occurs in-place without
+ changing URLs.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-minify">rewrite_javascript_external</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by rewrite_javascript. Rewrites JavaScript external files to remove
+ excess whitespace and comments. In OptimizeForBandwidth mode, the minification
+ occurs in-place without changing URLs.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-minify">rewrite_javascript_inline</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by rewrite_javascript. Rewrites inline JavaScript blocks to remove
+ excess whitespace and comments.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-source-maps-include"
+ >include_js_source_maps</a></code></td>
+ <td>No</td><td>No</td><td>
+ Adds source maps to rewritten JavaScript files.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-combine">combine_javascript</a></code></td>
+ <td>Yes</td><td>No</td><td>Combines multiple script elements
+ into one.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-canonicalize-js"
+ >canonicalize_javascript_libraries</a></code></td>
+ <td>No</td><td>No</td><td>Redirects JavaScript libraries to a
+ JavaScript hosting service.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-inline">inline_css</a></code></td>
+ <td>Yes</td><td>No</td><td>Inlines small CSS files into the HTML
+ document.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-css-inline-google-fonts"
+ >inline_google_font_css</a></code></td>
+ <td>No</td><td>No</td><td>Inlines small CSS files used by
+ fonts.googleapis.com into the HTML document.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-inline">inline_javascript</a></code></td>
+ <td>Yes</td><td>No</td><td>Inlines small JS files into the HTML
+ document.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-local-storage-cache"
+ >local_storage_cache</a></code></td>
+ <td>No</td><td>No</td><td>Cache inlined resources in HTML5 local
+ storage.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-insert-ga">insert_ga</a></code></td>
+ <td>No</td><td>No</td><td>Adds the Google Analytics snippet to
+ each HTML page.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#rewrite_images"
+ >rewrite_images</a></code></td>
+ <td>Yes</td><td>No</td><td>Optimizes images, re-encoding them,
+ removing excess pixels, and inlining small images. In
+ OptimizeForBandwidth mode, the minification occurs in-place
+ without changing URLs.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#progressive">
+ convert_jpeg_to_progressive</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Converts larger jpegs to progressive
+ format. Implied by recompress images.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#png_to_jpeg">
+ convert_png_to_jpeg</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Converts gif and png images into jpegs if they
+ appear to be less sensitive to compression artifacts and lack alpha
+ transparency. Implied by recompress images.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#convert_jpeg_to_webp">
+ convert_jpeg_to_webp</a></code></td>
+ <td>Yes</td><td>Yes</td><td> Producess lossy webp rather than jpeg images
+ for browsers that support webp. Implied by recompress images.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#convert_to_webp_animated">
+ convert_to_webp_animated</a></code></td>
+ <td>No</td><td>No</td><td> Replaces animated gif images with webp images
+ on browsers that support the format.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#convert_to_webp_lossless">
+ convert_to_webp_lossless</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by rewrite_images. Replaces png and non-animated gif images
+ with webp images on browsers that support the format.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#insert_image_dimensions"
+ >insert_image_dimensions</a></code></td>
+ <td>No</td><td>No</td><td>
+ Adds <code>width</code> and <code>height</code> attributes to
+ <code><img></code> tags that lack them.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#inline_images">
+ inline_images</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by rewrite_images. Replaces small images by
+ <code>data:</code> urls.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#recompress_images"
+ >recompress_images</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by rewrite_images. Recompresses images, removing excess
+ metadata and transforming gifs into pngs.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#recompress_jpeg"
+ >recompress_jpeg</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by recompress_images. Recompresses jpegs, removing excess
+ metadata.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#recompress_png"
+ >recompress_png</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by recompress_images. Recompresses pngs, removing excess
+ metadata.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#recompress_webp"
+ >recompress_webp</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by recompress_images. Recompresses webps, removing excess
+ metadata.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#convert_gif_to_png"
+ >convert_gif_to_png</a></code></td>
+ <td>Yes</td><td>Yes</td><td>
+ Implied by recompress_images. Optimizes gifs to pngs.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#strip_image_color_profile"
+ >strip_image_color_profile</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Implied by recompress_images. Strips color
+ profile info from images.</td>
+ </tr>
+ <tr>
+ <td><code><a
+ href="reference-image-optimize#strip_image_meta_data"
+ >strip_image_meta_data</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Implied by recompress_images. Strips EXIF
+ meta data from images.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#jpeg_sampling"
+ >jpeg_sampling</a></code></td>
+ <td>Yes</td><td>Yes</td><td>Implied by recompress_images. Reduces the
+ color sampling of jpeg images to 4:2:0.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#resize_images"
+ >resize_images</a></code></td>
+ <td>Yes</td><td>No</td><td>Implied by rewrite_images. Resizes images
+ when the corresponding <code><img></code> tag specifies a
+ smaller <code>width</code> and <code>height</code>.</td>
+ </tr>
+ <tr>
+ <td><code><a href="reference-image-optimize#resize_rendered_image_dimensions"
+ >resize_rendered_image_dimensions</a></code></td>
+ <td>Yes</td><td>No</td><td>Implied by rewrite_images. Resizes
+ an image when the rendered dimensions of the image are smaller
+ than the actual image.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-inline-preview-images"
+ >inline_preview_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Uses inlined low-quality images as placeholders which will be
+ replaced with original images once the web page is loaded.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-inline-preview-images#resize_mobile_images"
+ >resize_mobile_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Works just like <code>inline_preview_images</code>, but uses smaller
+ placeholder images and only serves them to mobile browsers.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-comment-remove">remove_comments</a></code></td>
+ <td>No</td><td>No</td><td>
+ Removes comments in HTML files (but not in inline JavaScript or CSS).
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-whitespace-collapse"
+ >collapse_whitespace</a></code></td>
+ <td>No</td><td>No</td><td>
+ Removes excess whitespace in HTML files (avoiding
+ <code><pre></code>,
+ <code><script></code>,
+ <code><style></code>, and
+ <code><textarea></code>).
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-attribute-elide"
+ >elide_attributes</a></code></td>
+ <td>No</td><td>No</td><td>
+ Removes attributes which are not significant according to the
+ HTML spec.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend">extend_cache</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Extends cache lifetime of CSS, JS, and image resources that have not
+ otherwise been optimized, by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend">extend_cache_css</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by extend_cache. Extends cache lifetime of otherwise unoptimized
+ CSS resources by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend">extend_cache_images</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by extend_cache. Extends cache lifetime of otherwise unoptimized
+ images by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend">extend_cache_scripts</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Implied by extend_cache. Extends cache lifetime of otherwise unoptimized
+ scripts by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-cache-extend-pdfs"
+ >extend_cache_pdfs</a></code></td>
+ <td>No</td><td>No</td><td>
+ Extends cache lifetime of PDFs by signing URLs with a content hash.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-image-sprite">sprite_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Combine background images in CSS files into one sprite.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-domain-rewrite">rewrite_domains</a></code></td>
+ <td>No</td><td>No</td><td>
+ Rewrites the domains of resources not otherwise touched by
+ PageSpeed, based on <code>MapRewriteDomain</code> and
+ <code>ShardDomain</code> settings in the config file.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-trim-urls">trim_urls</a></code></td>
+ <td>No</td><td>No</td><td>
+ Shortens URLs by making them relative to the base URL.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-pedantic">pedantic</a></code></td>
+ <td>No</td><td>No</td><td>
+ Add default types for <script> and <style> tags if the type
+ attribute is not present and the page is not HTML5. The purpose of
+ this filter is to help ensure that PageSpeed does not break HTML4
+ validation.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-quote-remove">remove_quotes</a></code></td>
+ <td>No</td><td>No</td><td>
+ Removes quotes around HTML attributes that are not lexically required.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-instrumentation-add"
+ >add_instrumentation</a></code></td>
+ <td>No</td><td>No</td><td>
+ Adds JavaScript to page to measure latency and send back to the server.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-convert-meta-tags"
+ >convert_meta_tags</a></code></td>
+ <td>Yes</td><td>No</td><td>
+ Adds a response header for each <code>meta</code> tag with an
+ <code>http-equiv</code> attribute.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-js-defer">defer_javascript</a></code></td>
+ <td>No</td><td>No</td><td>
+ Defers the execution of JavaScript in HTML until page load complete.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-dedup-inlined-images"
+ >dedup_inlined_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Replaces repeated inlined images with JavaScript that loads the image
+ from the first occurence of the image.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-lazyload-images">lazyload_images</a></code></td>
+ <td>No</td><td>No</td><td>
+ Loads images when they become visible in the client viewport.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-insert-dns-prefetch"
+ >insert_dns_prefetch</a></code></td>
+ <td>No</td><td>No</td><td>
+ Inserts <code><link rel="dns-prefetch"
+ href="//www.example.com"></code> tags to reduce DNS resolution
+ time.</td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-hint-preload-subresources"
+ >hint_preload_subresources</a></code></td>
+ <td>No</td><td>No</td><td>
+ Inserts <code>Link:</example.css>; rel=preload</code>
+ headers to permit earlier fetching of important resources.</td>
+ </tr>
+ <tr>
+ <td><code><a href="system#in_place_optimize_for_browser"
+ >in_place_optimize_for_browser</a></code></td>
+ <td>No</td><td>Yes</td><td>
+ Perform browser-dependent <a href="system#ipro">in-place resource
+ optimizations</a>.</td>.
+ </tr>
+ </tbody>
+</table>
+
+<h2 id="forbidding">Forbidding All Disabled Filters</h2>
+<p>
+You can
+<a href="experiment#PerRequest">enable filters for a specific request</a>
+using either query parameters or request headers, and you can
+<a href="configuration#htaccess">enable filters in sub-directories</a>
+using the <code>EnableFilters</code> directive.
+</p>
+<p>
+In both cases you can enable filters that are disabled or not explicitly
+enabled in the configuration file, however there are situations where
+this is undesirable, such as when a filter has been expressly disabled because
+it breaks a page, or because a filter imposes too great a load on the server.
+</p>
+<p>
+All disabled filters can be forced off with:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedForbidAllDisabledFilters true</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ForbidAllDisabledFilters true;</pre>
+</dl>
+
+<p>
+Note that in this context <em>disabled filters</em> means all filters that
+are not enabled by the <code>RewriteLevel</code> or
+<code>EnableFilters</code> directives.
+</p>
+<p>
+This directive can be used in <a href="configuration#htaccess">location-specific
+configuration sections</a>.
+</p>
+
+<h2 id="checking-filter-config">Checking Which Filters Are Enabled</h2>
+<p>
+If you want to see exactly which filters are enabled on a virtual host, you
+can do so by going to that host's <a href="admin">admin or statistics</a> page.
+</p>
+
+<h2 id="tuning">Tuning the Filters</h2>
+<p>
+Once the rewriters are selected, some of them may also be tuned. These
+parameters control the inlining and outlining thresholds of various resources.
+</p>
+
+<pre class="prettyprint">
+CssFlattenMaxBytes 102400 (was 2048 prior to 1.9.32.1)
+CssImageInlineMaxBytes 0
+CssInlineMaxBytes 2048
+CssOutlineMinBytes 3000
+ImageInlineMaxBytes 3072
+ImageJpegNumProgressiveScans -1
+ImageJpegNumProgressiveScansForSmallScreens -1
+ImageLimitOptimizedPercent 100
+ImageLimitResizeAreaPercent 100
+ImageRecompressionQuality 85
+ImageResolutionLimitBytes 32000000
+JpegRecompressionQuality -1
+JpegRecompressionQualityForSmallScreens 70
+WebpRecompressionQuality 80
+WebpAnimatedRecompressionQuality 70
+WebpRecompressionQualityForSmallScreens 70
+JsInlineMaxBytes 2048
+JsOutlineMinBytes 3000
+MaxInlinedPreviewImagesIndex -1
+MinImageSizeLowResolutionBytes 3072
+RetainComment "[WILDCARD PATTERN]"
+RewriteRandomDropPercentage 0
+</pre>
+
+<p class="note"><strong>Note:</strong>
+The default settings are reasonable and intuitive, but have not been
+experimentally tuned.
+</p>
+<p>
+These directives can be used
+in <a href="configuration#htaccess">location-specific configuration
+sections</a>.
+</p>
+
+<h2 id="beacons">Controlling the use of beacons</h2>
+<p>
+The <code><a href="filter-lazyload-images">lazyload_images</a></code>,
+<code><a href="filter-inline-preview-images">inline_preview_images</a></code>,
+and <code><a href="reference-image-optimize#inline_images">inline_images</a>
+</code> filters, use a <a href="faq#beacons">beacon</a> to collect information
+about the rewritten page so as to optimize the rewriting process. The beacon
+is a <code>POST</code> request sent back by JavaScript inserted into the page
+by the filter. The use of this beacon is on by default but it can be disabled
+using:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCriticalImagesBeaconEnabled false</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CriticalImagesBeaconEnabled false;</pre>
+</dl>
+<p>
+If you disable image beacons but enable filters that use them, the filters will
+work but not as well as when beacons are enabled.
+</p>
+<p>
+This directive can be used in all scopes including
+<a href="configuration#htaccess">location-specific configuration sections</a>.
+</p>
+
+<h3 id="FinderPropertiesCacheExpirationTimeMs">Controlling beacon expiry</h3>
+<strong>Note: New option as of 1.12.34.1</strong>
+<p>
+By default beacon data is considered valid for two hours, but if your site has a
+lot of pages that change rarely and get few hits you might want to raise this
+limit:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedFinderPropertiesCacheExpirationTimeMs TtlInMs</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed FinderPropertiesCacheExpirationTimeMs TtlInMs;</pre>
+</dl>
+
+<h2 id="preserveurls">Preserving URLs in HTML</h2>
+<p>
+PageSpeed filters often modify the URLs of resources in HTML pages. This is
+generally harmless but it has the potential to break pages whose JavaScript
+expects to read or modify the URLs in the page.
+</p>
+<p>
+image_preserve_urls, css_preserve_urls, and js_preserve_urls
+will suppress URL rewriting actions for the respective resource types. Those
+filters that require modifications to the URL are disabled by the preserve
+directives.
+</p>
+<p class="note">
+<strong>Note:</strong>
+Even though resource URLs are unchanged that does not mean that they cannot
+still be optimized. For instance,
+<a href="system#ipro">InPlaceResourceOptimization</a> still works since it does
+not alter URLs. Turning on in place resource optimization is recommended when
+enabling any of the options to preserve URLs. In version 1.9.32.1 and later
+in place resource optimization is enabled by default.
+</p>
+<p>
+Enabling image_preserve_urls will <a href="#forbidding">forbid</a>
+the use of the following filters:
+<code><a href="filter-inline-preview-images">inline_preview_images</a></code>,
+<code><a href="filter-lazyload-images">lazyload_images</a></code>,
+<code><a href="filter-cache-extend">extend_cache_images</a></code>,
+<code><a href="filter-image-optimize#inline_images">inline_images</a></code>,
+and <code><a href="filter-image-sprite">sprite_images</a></code>.
+</p>
+<p>
+Enabling css_preserve_urls will <a href="#forbidding">forbid</a> the use
+of the following filters:
+<code><a href="filter-css-combine">combine_css</a></code>,
+<code><a href="filter-cache-extend">extend_cache_css</a></code>,
+<code><a href="filter-css-inline">inline_css</a></code>,
+<code><a href="filter-css-inline-import">inline_import_to_link</a></code>,
+and <code><a href="filter-css-outline">outline_css</a></code>.
+</p>
+<p>
+Enabling js_preserve_urls will <a href="#forbidding">forbid</a> the use
+of the following filters:
+<code><a href="filter-canonicalize-js">canonicalize_javascript_libraries</a></code>,
+<code><a href="filter-js-combine">combine_javascript</a></code>,
+<code><a href="filter-js-defer">defer_javascript</a></code>,
+<code><a href="filter-cache-extend">extend_cache_javascript</a></code>,
+<code><a href="filter-js-inline">inline_javascript</a></code>,
+and <code><a href="filter-js-outline">outline_javascript</a></code>.
+</p>
+
+<h2 id="RewriteRandomDropPercentage">Reducing Load by Randomly Dropping
+Expensive Rewrites</h2>
+To reduce processing load, PageSpeed can be configured to optimize
+the most frequently fetched resources, leaving infrequently fetched
+resources alone. This is accomplished by randomly dropping expensive
+(CSS and image) rewrites. Frequently fetched resources will have a higher
+probability of being rewritten than infrequently fetched resources.
+Over time, frequently accessed resources will be optimized and cached so
+a page will be fully optimized. Infrequently accessed pages will be left
+unoptimized or partially optimized, saving CPU time and cache space.
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRewriteRandomDropPercentage Percent</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RewriteRandomDropPercentage Percent;</pre>
+</dl>
+<p>
+This is a load-tuning parameter (integer between 0 and 100 inclusive)
+that controls the percentage of resource rewrites that are randomly
+dropped. Currently only CSS and image rewrites are randomly dropped,
+as they are the CPU intensive rewrite tasks. A value of 100 means all
+such rewrites are dropped and a value of 0 means no rewrites are
+dropped. A value of 75 means that 75% of image and CSS rewrites
+(selected at random) are dropped. Do not set this parameter to 100 in
+order prevent optimization of images and CSS files, it is more efficient
+to instead disable the image and/or CSS filters.
+</p>
+<p>
+As an example, if the value is 90 then an image fetched only once will
+be optimized with 10% probability while an image fetched 50 times
+will be optimized with 99.65% probability (1 - 0.9^50). You
+may need to tune this parameter to find a value that provides the
+right load on your servers and still provides sufficient image and CSS
+optimization.
+</p>
+<p class="note"><strong>Note: Images within CSS files are not randomly dropped
+as this would lead to partially optimized CSS resources.</strong></p>
+
+<h2 id="multi_server">Configuring for Multiple Servers</h2>
+<p>
+When running PageSpeed on multiple servers, it is important that
+each have the same configuration file. This ensures that when a
+browser requests an image or other resource from one server, it will
+be optimized using the same options that were used to compute the
+optimized resource when HTML was served. It is helpful to
+use <a href="system.html#memcached">memcached</a> to share cache
+between servers as it improves multi-server performance and
+scalability, but it is still important that the configurations are
+consistent to get the desired behavior when optimized images are
+evicted from cache.
+</p>
+
+<p>
+Note also that <a href="configuration#htaccess">location-specific configuration
+settings</a> should be consistent between the HTML paths and the resource
+paths.</p>
+
+<p id="add_options_to_urls" class="note">
+
+<p>In some sites, the URL path layout or network deployment strategy may
+not allow for consistent configuration between HTML and images.
+PageSpeed offers a workaround for such sites by encoding relevant
+configuration settings for each rewritten resource into the URLs:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedAddOptionsToUrls on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed AddOptionsToUrls on;</pre>
+</dl>
+
+<p>
+This adds an encoding of the options that are relevant to each rewritten
+resource to the URLs. While the produced URLs are larger, this provides a
+mechanism to propagate configuration without having to share a configuration
+file. For example, a site with image recompression on and JPEG compression set
+to 85 would see URLs like
+<code>http://example.com/ximage.jpg.pagespeed.gp+jw+pj+rj+rp+rw+iq=85.ic.HASH.jpg</code>.
+While it is better to have the extra configuration details in the configuration
+file, this option offers a fallback plan when that is not practical.
+</p>
+
+<h2 id="custom-fetch-headers">Custom Fetch Headers</h2>
+
+<p>
+When not using <a href="domains#ModPagespeedLoadFromFile"
+>LoadFromFile</a>, PageSpeed has to make HTTP requests for sub-resources of a
+>page in order to rewrite them. Consider the following HTML snippet:
+</p>
+<pre class="prettyprint">
+ ...
+ <body>
+ <img src="example.jpg">
+ ...
+</pre>
+<p>
+If the <a href="filter-image-optimize">rewrite_images</a>
+filter is enabled, PageSpeed needs to fetch <code>example.jpg</code> in order
+to inline, compress, or otherwise optimize it. If you would like custom
+headers to be sent with all sub-resource fetches like this one, you can use
+the <code>CustomFetchHeader</code> directive:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedCustomFetchHeader CustomHeader CustomHeaderValue
+ModPagespeedCustomFetchHeader AnotherCustomHeader AnotherValue</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed CustomFetchHeader CustomHeader CustomHeaderValue;
+pagespeed CustomFetchHeader AnotherCustomHeader AnotherValue;</pre>
+</dl>
+
+
+<h2 id="unsupported-filters">Unsupported Filters</h2>
+<p>
+The PageSpeed code base contains a number of additional filters whose use is
+unsupported. Some of these are experimental; note that using experimental
+filters is likely to result in crashes or site breakage. Others are used for
+debugging specific problems with PageSpeed:
+</p>
+ <table>
+ <thead><tr>
+ <th>Debugging filter name</th>
+ <th>Brief Description</th>
+ </tr></thead>
+ <tr>
+ <td><code>add_base_tag</code></td>
+ <td>
+ Adds a <code><base></code> element to the beginning of
+ the <code><head></code> that reflects the base url PageSpeed
+ is using to resolve relative url references in the page.</td>
+ </tr>
+ <tr>
+ <td id="debug"><code>debug</code></td>
+ <td>
+ Adds comments to the page describing actions by certain filters, and
+ attempts to serve JavaScript injected by PageSpeed in source form
+ rather than compiled and minified.
+ </td>
+ </tr>
+ <tr>
+ <td><code>deterministic_js</code></td>
+ <td>
+ Attempts to provide deterministic JavaScript behavior on each page, for
+ example by replacing the timer and random number generator with
+ functions that return the same sequence of values on every page load.
+ </td>
+ </tr>
+ <tr>
+ <td><code><a href="filter-strip-scripts">strip_scripts</a></code></td>
+ <td>
+ Removes all script tags from the document.</td>
+ </tr>
+ </table>
+<p class="note">
+<strong>Note: None of the above filters should be used to serve live traffic.</strong>
+</p>
+
+<h2 id="remote-configuration">Remote Configuration</h2>
+<p class="note"><strong>Note: New feature as of 1.10.33.0</strong></p>
+<p>
+PageSpeed filters and configurations can also be specified by an external
+"Remote Configuration" file. The remote configuration will override
+the main configuration file, override <code>.htaccess</code> configurations, and
+be overridden by any query-level parameters.
+<p>
+To specify the <code>RemoteConfigurationUrl</code>:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRemoteConfigurationUrl https://example.com/remote.conf</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RemoteConfigurationUrl https://example.com/remote.conf;</pre>
+</dl>
+<p>
+The syntax for the remote configuration file is similar to that of the
+<code>.htaccess</code> configurations with a few notable exceptions. Directives
+don't use <code>ModPagespeed</code> as a prefix. Comments are specified by
+<code>#</code> and must be on their own line. Filters and options with
+<code>DirectoryScope</code> or higher may be applied with the remote
+configuration. Any invalid lines in the remote configuration will be skipped, a
+warning will be logged, and the remaining lines will still be parsed. The remote
+configuration terminates with a line beginning with
+<code>EndRemoteConfig</code>, and any lines after this are ignored. If the
+configuration file does not contain a line beginning with
+<code>EndRemoteConfig</code> no configuration will be applied. An example
+configuration for enabling the <code>remove_comments</code> filter is as
+follows.
+<p>
+<pre>
+ # Enable the remove_comments filter.
+ EnableFilter remove_comments
+ EndRemoteConfig
+ # Everything after the previous line will be ignored.
+</pre>
+</p>
+<p>
+The remote configuration file will be fetched on the server's startup,
+and cached for the extent determined by the remote server's
+<code>Cache-Control</code> and <code> Expires</code> headers. For example, if
+the remote configuration hosting server provides the header
+<code>Cache-Control: max-age=3600</code>, the next fetch of the
+remote configuration will happen at the first request after 3600 seconds.
+Failed fetches after successful fetches will continue to serve the stale config.
+The remote configuration should be used in addition to your original
+configuration. The remote configuration is not guaranteed to be fetched and
+applied to every request, so the site should not rely on the remote
+configuration in order to work.
+</p>
+The timeout for the fetching the remote configuration file can also be
+specified. The default timeout is one second. To specify the fetching timeout.
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRemoteConfigurationTimeoutMs 1500</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RemoteConfigurationTimeoutMs 1500;</pre>
+</dl>
+Fetching the remote configuration will block for up to the specified timeout.
+<p class="note"><strong>Note:</strong>
+Remote configurations can not be fetched from the same server that is running
+the instance of pagespeed.
+</p>
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/configuration.html b/doc/configuration.html
new file mode 100644
index 0000000..619f199
--- /dev/null
+++ b/doc/configuration.html
@@ -0,0 +1,638 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>PageSpeed Configuration</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>PageSpeed Configuration</h1>
+
+<h2 id="module">Enabling the Module</h2>
+<p>
+PageSpeed contains an "output filter" plus several content handlers.
+<p class="note">
+<strong>Note:</strong>
+The location of the configuration file is dependent both on the Linux
+distribution on which PageSpeed is installed and on whether you're using
+PageSpeed with Apache or Nginx.
+</p>
+
+<p>
+In Apache the configuration file
+is <code>pagespeed.conf</code> and will be in either:
+<pre>
+Debian/Ubuntu: /etc/apache2/mods-available/
+CentOS/Fedora: /etc/httpd/conf.d/
+</pre>
+In Nginx the configuration typically should go in your <code>nginx.conf</code>
+which for source installs defaults to being in:
+<pre>
+/usr/local/nginx/conf/
+</pre>
+</p>
+
+<p>
+In Apache PageSpeed is enabled automatically when you install the module while
+in Nginx you need to add several lines to your <code>nginx.conf</code>. In
+every <code>server</code> block where PageSpeed is enabled add:
+
+<pre>
+pagespeed on;
+
+# Needs to exist and be writable by nginx. Use tmpfs for best performance.
+pagespeed FileCachePath /var/ngx_pagespeed_cache;
+
+# Ensure requests for pagespeed optimized resources go to the pagespeed handler
+# and no extraneous headers get set.
+location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
+ add_header "" "";
+}
+location ~ "^/pagespeed_static/" { }
+location ~ "^/ngx_pagespeed_beacon$" { }
+</pre>
+
+See the <a href="admin#config">Admin Page documentation</a> for
+instructions on how to configure handlers to provide visibility and
+control into PageSpeed's operation.
+
+<h2 id="on_off">Turning the module on and off</h2>
+<!-- keep old anchors so as not to break existing links -->
+<a name="on_off_nginx"></a><a name="nginx_specific"></a>
+
+<h3 id=on>Setting the module on</h3>
+
+<p>
+
+To turn PageSpeed on, just set:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeed on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed on;</pre>
+</dl>
+
+<h3 id=standby>Setting the module to standby</h3>
+
+<p>
+
+PageSpeed has a standby mode where by default it won't make changes to your site
+but it will process two kinds of PageSpeed-specific requests:
+
+<ul>
+ <li><p>Requests with <a href="experiment#PerRequest">PageSpeed query
+ parameters</a>. These allow you to have PageSpeed off in your main
+ configuration, but manually make requests to see how your site would look
+ under various combinations of filters and options.
+ <li><p>Requests for <code>.pagespeed.</code> resources. When PageSpeed is
+ running it creates various kinds of optimized resources, and gives them
+ names containing <code>.pagespeed.</code>. If you turned
+ PageSpeed <a href="#unplugged">fully off</a> then lingering requests to
+ these resorces would fail. In standby mode these requests are still
+ served as if PageSpeed were enabled.
+</ul>
+
+<p>
+
+In versions 1.12 and earlier only mod_pagespeed supported standby mode, via
+the <code>off</code> setting:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeed off</pre>
+</dl>
+
+<p>
+
+In versions 1.13.35.1 and later, both mod_pagespeed and ngx_pagespeed
+support <code>standby</code>:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeed standby</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed standby;</pre>
+</dl>
+
+<h3 id=unplugged>Setting the module fully off</h3>
+
+To turn PageSpeed fully off, set:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeed unplugged</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed unplugged;</pre>
+</dl>
+
+<p class=warning><b>Warning:</b> do not set ngx_pagespeed
+to <code>unplugged</code> in 1.12.34.1 and earlier. That will result in
+crashes. With those versions, use <code>off</code> instead
+of <code>unplugged</code>.
+
+<p>
+
+The <code>on</code>, <code>off</code>, and (in 1.13.35.1 and
+later) <code>standby</code> values can be used in
+<a href="#htaccess"><code>.htaccess</code> files,
+<code><Directory></code></a> scopes, <code>query parameters</code>, and
+<code>headers</code>. The <code>unplugged</code> value can only be used in the
+top-level Apache configuration and in virtual hosts. Note that
+<code>ModPagespeed on</code> in a virtual host can override a top-level
+<code>ModPagespeed unplugged</code> directive.
+</p>
+
+<h2 id="apache_specific">Apache-Specific Configuration</h2>
+
+<h3 id="output_filter">Setting up the Output Filter</h3>
+
+<p>
+The output filter is used to parse, optimize, and re-serialize HTML
+content that is generated elsewhere in the Apache server.
+</p>
+<pre class="prettyprint">
+# Direct Apache to send all HTML output to the mod_pagespeed output handler.
+AddOutputFilterByType MOD_PAGESPEED_OUTPUT_FILTER text/html
+</pre>
+<p class="note"><strong>Note:</strong> mod_pagespeed automatically enables
+<code>mod_deflate</code> for compression.
+</p>
+
+<h3 id="apache24">Support for Apache 2.4.x</h3>
+<p>
+<code>mod_pagespeed</code> is compatible with Apache 2.2.x and Apache 2.4.x
+series, versions 2.4.2 and newer. Please note that Apache 2.4.1 has a bug that
+may cause stability problems in combination with <code>mod_pagespeed</code>,
+so use with 2.4.1 is strongly discouraged.
+</p>
+
+<p>
+As Apache 2.4 is not API compatible with 2.2, support for it is provided
+via a separate module binary, <code>mod_pagespeed_ap24.so</code> instead of the
+usual <code>mod_pagespeed.so</code>. The configuration provided in our binary
+packages will normally load the right module version automatically. However,
+if you upgrade the CentOS packages from an earlier version, the needed
+configuration change may not get applied on top of a user-customized
+<code>pagespeed.conf</code>, so you may need to adjust the
+<code>LoadModule</code> line manually.
+</p>
+
+<p>
+Source builds with <code>mod_pagespeed</code>-provided Apache headers will
+build both 2.2.x and 2.4.x binaries as well, and you will need to add a
+<code>LoadModule</code> line matching the server version in use, or use
+a pattern similar to:
+<pre class="prettyprint">
+<IfModule !mod_version.c>
+ LoadModule version_module /usr/lib/apache2/modules/mod_version.so
+</IfModule>
+
+<IfVersion < 2.4>
+ LoadModule pagespeed_module /usr/lib/apache2/modules/mod_pagespeed.so
+</IfVersion>
+<IfVersion >= 2.4.2>
+ LoadModule pagespeed_module /usr/lib/apache2/modules/mod_pagespeed_ap24.so
+</IfVersion>
+</pre>
+to auto-detect. Builds against system Apache headers will only be compatible
+with that version family, and will always produce a single module named
+<code>mod_pagespeed.so</code>.
+</p>
+
+<h2 id="honor-csp">Honoring Content-Security-Policy Headers</h2>
+<p>
+ As of 1.13.35.1 PageSpeed is able to adapt its optimizations according to any
+ Content Security Policies specified in the response headers. In this release
+ you need to opt-in into this feature, future releases may turn it on by
+ default.
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedHonorCsp on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed HonorCsp on;</pre>
+</dl>
+
+<h2 id="respectvary">Respecting Vary Headers</h2>
+<p>
+In order to maximize the number of resources that PageSpeed can rewrite, by
+default the module does not respect <code>Vary: User-Agent</code> and
+other <code>Vary</code> headers on resource files, such as JavaScript and css
+files. By disregarding the <code>Vary</code> headers, PageSpeed is able to keep
+the size of the cache down. PageSpeed will <em>always</em> respect <code>Vary:
+Accept-Encoding</code>, regardless of this setting. PageSpeed will
+also <em>always</em> respect <code>Vary</code> headers on <code>HTML</code>
+files, regardless of this setting.
+</p>
+<p>
+If a site has resources that legitimately vary on <code>User-Agent</code>, or
+on some other attribute, then in order to preserve that behavior, you must
+add</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedRespectVary on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed RespectVary on;</pre>
+</dl>
+<p>to your configuration file.</p>
+<p>Please note that turning on this option will disable optimization of any
+resources with <code>Vary</code> headers, apart from
+<code>Vary: Accept-Encoding</code>.</p>
+
+<h2 id="notransform">Honoring no-transform Cache-Control Headers</h2>
+<p>
+By default, PageSpeed does not rewrite resources that have
+<code>Cache-Control: no-transform</code> set in the Response Header. This is
+true for all types of resources, such as JavaScript, images, CSS etc. By
+respecting <code>Cache-Control: no-transform</code> headers, PageSpeed cannot
+optimize resources that could otherwise be rewritten.
+</p>
+<p>
+To optimize resources irrespective of <code>Cache-Control: no-transform</code>
+headers, you must add</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">ModPagespeedDisableRewriteOnNoTransform off</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">pagespeed DisableRewriteOnNoTransform off;</pre>
+</dl>
+<p>to your configuration file.</p>
+<p>Please note that PageSpeed will always respect
+<code>Cache-Control: no-transform</code> headers on <code>HTML</code> files
+irrespective of the setting. And also, PageSpeed will always retain the
+<code>Cache-Control: no-transform</code> headers on the resource irrespective of
+the setting so that the downstream cache control mechanisms do not get affected.
+</p>
+
+<h2 id="lower_case">Lower-casing HTML element and attribute names</h2>
+<p>
+HTML is
+<a href="http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-5353782642-h2">
+ case-insensitive</a>, whereas XML and XHTML are not. Web performance
+<a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload#consistency">Best Practices</a> suggest using lowercase
+keywords, and PageSpeed can safely make that transformation in HTML
+documents.
+</p>
+<p>
+In general, PageSpeed knows whether a document is HTML or not
+via <code>Content-Type</code> tags in HTTP headers, and <code>DOCTYPE</code>.
+However, many web sites have <code>Content-Type: text/html</code> for resources
+that are actually XML documents.
+</p>
+<p>
+If PageSpeed lowercases keywords in XML pages, it can break the consumers of
+such pages, such as Flash. To be conservative and avoid breaking such pages,
+PageSpeed does not lowercase HTML element and attribute names by
+default. However, you can sometimes achieve a modest improvement in the size of
+compressed HTML by enabling this feature with:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedLowercaseHtmlNames on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed LowercaseHtmlNames on;</pre>
+</dl>
+
+<p>
+
+These directives can be used in <a href="#htaccess">location-specific
+configuration sections</a>.
+</p>
+
+<h3>Risks</h3>
+<p>
+This switch is only risky in the presence of XML files that are
+incorrectly served with <code>Content-type: text/html</code>.
+Lower-casing XML element and attribute may affect whatever software is
+reading the XML.
+</p>
+
+<h2 id="ModifyCachingHeaders">Preserving HTML caching headers</h2>
+<p>
+ By default, PageSpeed serves all HTML with
+ <code>Cache-Control: no-cache, max-age=0</code> because the transformations
+ made to the page may not be cacheable for extended periods of time.
+</p>
+<p>
+ If you want to force PageSpeed to leave the original HTML caching headers
+ you can add:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedModifyCachingHeaders off</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ModifyCachingHeaders off;</pre>
+</dl>
+<p class="note">
+ <b>Note:</b> We do not suggest you turn this option off. It breaks PageSpeed's
+ caching assumptions and can lead to unoptimized HTML being served from a proxy
+ caches set up in front of the server. If you do turn it off, we suggest that
+ you do not set long caching headers to HTML or users may receive stale or
+ unoptimized content.
+</p>
+
+<h2 id="XHeaderValue">Specifying the value for the PageSpeed header</h2>
+<p>
+ By default, PageSpeed adds an header, <code>X-Mod-Pagespeed</code> in
+ Apache, <code>X-Page-Speed</code> in Nginx, with the version of PageSpeed
+ being used. The format of this header is:
+</p>
+
+<pre>[Major].[Minor].[Branch].[Point]-[Commit]</pre>
+
+<p>
+ For example:
+</p>
+
+<pre>1.9.32.3-4448</pre>
+
+<p>
+ We update these following this schedule:
+</p>
+
+<dl>
+ <dt>Major Version</dt>
+ <dd>Incremented when we make very large changes.</dd>
+
+ <dt>Minor Version</dt>
+ <dd>Incremented for each release since the last major version</dd>
+
+ <dt>Branch Number</dt>
+ <dd>Incremented for every release. Always increasing.</dd>
+
+ <dt>Point Number</dt>
+ <dd>Incremented each time we build a new release candidate or patch release,
+ resets on each minor release.</dd>
+
+ <dt>Commit Number</dt>
+ <dd>Incremented each time we accept a commit to the PSOL trunk. Always
+ increasing.</dd>
+</dl>
+
+<p>
+ All servers running a given release will have the same value for this header
+ by default. If you would like to change the value reported, you can use
+ the <code>XHeaderValue</code> directive to specify what to use instead:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedXHeaderValue "Powered By mod_pagespeed"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed XHeaderValue "Powered By ngx_pagespeed";</pre>
+</dl>
+<p class="note">
+ <b>Note:</b> You cannot suppress the injection of this header. This is because
+ it is used to prevent infinite loops and unnecessary rewrites when PageSpeed
+ fetches resources from an origin that also uses PageSpeed.
+</p>
+
+<h2 id="htaccess">Location-Specific Configuration</h2>
+<p>With an <code>.htaccess</code> file (Apache), <code><Directory></code>
+scope (Apache), or <code>location</code> block (Nginx) you can control most of
+the PageSpeed directives. Note, however, that the
+file-matching is only relevant to the HTML file, and not to any of the resources
+referenced from the HTML file. To restrict resources by directory, you must use
+the PageSpeed <a href="/speed/pagespeed/module/restricting_urls"><code
+>Allow</code> and <code>Disallow</code> directives</a>, using full paths or
+wildcards in those directives.</p>
+
+<p class="warning">
+ <b>Warning:</b> Resources and the HTML files that reference them must have
+ the same options. If they differ you may see poor performance and
+ inconsistent application of options.
+</p>
+
+<p>In Apache, the advantage of <code>.htaccess</code> is that it can be used in
+environments where the site administrator does not have access to the server
+configuration. However, there is a significant per-request overhead from
+processing <code>.htaccess</code> files.
+See <a href="http://httpd.apache.org/docs/2.2/howto/htaccess.html">The Apache
+HTTP Server Documentation</a>:</p>
+
+<p class="note">
+<strong>Note:</strong> You should avoid using <code>.htaccess</code> files
+completely if you have access to the httpd main server config file. Using
+<code>.htaccess</code> files slows down your Apache server. Any directive
+that you can include in a <code>.htaccess</code> file is better set in a
+<a href="http://httpd.apache.org/docs/2.2/mod/core.html#directory"
+ ><code><Directory></code></a> block, as
+it will have the same effect with better performance.
+</p>
+<p>
+<a href="#virtual-hosts">Virtual hosts</a> are generally a better way of
+configuring multiple sites on the same server.
+</p>
+
+<h2 id="virtual-hosts">Using PageSpeed With Virtual Hosts</h2>
+
+<p>By default, PageSpeed enables itself for the entire server, with global
+options propagating to all
+<a href="http://httpd.apache.org/docs/current/vhosts/">VirtualHost</a>s
+(Apache) or <code>server</code> blocks (Nginx). Options can be overridden
+per host, including the ability the limit which hosts PageSpeed runs on.</p>
+
+<p class="note"><strong>Note:</strong>
+When using Apache, it used to be possible to set <code>InheritVHostConfig</code>
+to "off" to stop global configuration from propagating to VHosts. However,
+enabling <code>InheritVHostConfig</code> makes PageSpeed options behave like
+other Apache options and has been the recommended configuration since 2012. The
+option has now been deprecated and will be forced to "on" in the next major
+PageSpeed release.</p>
+
+<dl>
+<dt>Apache:<dd><pre class="prettyprint lang-sh">
+ModPagespeed On
+ModPagespeedInheritVHostConfig on
+ModPagespeedFileCachePath "/var/cache/mod_pagespeed/"
+ModPagespeedEnableFilters combine_css,combine_javascript
+# Direct Apache to send all HTML output to the mod_pagespeed
+# output handler.
+AddOutputFilterByType MOD_PAGESPEED_OUTPUT_FILTER text/html
+
+NameVirtualHost *:80
+<VirtualHost *:80>
+ DocumentRoot /www/example1
+ ServerName www.example1.com
+ ModPagespeedMapRewriteDomain cdn.example1.com *example.com
+</VirtualHost>
+
+<VirtualHost *:80>
+ DocumentRoot /www/example2
+ ServerName www.example2.org
+ ModPagespeedMapRewriteDomain cdn.example2.org *example.org
+ # Don't want combine_css here
+ ModPagespeedDisableFilters combine_css
+</VirtualHost>
+
+<VirtualHost *:80>
+ DocumentRoot /www/example3
+ ServerName www.example3.org
+ # mod_pagespeed off for this virtual host
+ ModPagespeed Off
+</VirtualHost>
+</pre>
+<dt>Nginx:<dd><pre class="prettyprint">
+http {
+ pagespeed On;
+ pagespeed FileCachePath "/var/cache/ngx_pagespeed/";
+ pagespeed EnableFilters combine_css,combine_javascript;
+
+ server {
+ listen 80;
+ server_name www.example1.com;
+ root /www/example1;
+ pagespeed MapRewriteDomain cdn.example1.com *example.com;
+ }
+
+ server {
+ listen 80;
+ server_name www.example2.org;
+ root /www/example2;
+ pagespeed MapRewriteDomain cdn.example2.org *example.org;
+ # Don't want combine_css here
+ pagespeed DisableFilters combine_css;
+ }
+
+ server {
+ listen 80;
+ server_name www.example3.org;
+ root /www/example3;
+
+ # mod_pagespeed off for this virtual host
+ pagespeed off;
+ }
+</pre>
+</dl>
+
+<h2 id="preserve-url-relativity">Preserve URL Relativity</h2>
+
+<p>
+ Previous versions of PageSpeed would rewrite relative URLs into absolute URLs.
+ This wastes bytes and can cause problems for sites that sit behind HTTPS
+ terminators.
+</p>
+<p>
+ With <code>PreserveUrlRelativity on</code>, PageSpeed will keep URLs the way
+ they were found. Some examples:
+</p>
+<table>
+ <tr>
+ <th>Original URL</th>
+ <th>Rewritten URL</th>
+ </tr><tr>
+ <td><code>foo/bar.png</code></td>
+ <td><code>foo/bar.png.pagespeed.ic.Hash.png</code></td>
+ </tr><tr>
+ <td><code>/bar.png</code></td>
+ <td><code>/bar.png.pagespeed.ic.Hash.png</code></td>
+ </tr><tr>
+ <td><code>//example.com/bar.png</code></td>
+ <td><code>//example.com/bar.png.pagespeed.ic.Hash.png</code></td>
+ </tr><tr>
+ <td><code>http://example.com/bar.png</code></td>
+ <td><code>http://example.com/bar.png.pagespeed.ic.Hash.png</code></td>
+ </tr>
+</table>
+</ul>
+<p>
+ To enable this option, add:
+</p>
+<dl>
+ <dt>Apache:
+ <dd><pre class="prettyprint">ModPagespeedPreserveUrlRelativity on</pre>
+ <dt>Nginx:
+ <dd><pre class="prettyprint">pagespeed PreserveUrlRelativity on;</pre>
+</dl>
+<p>to your configuration file.</p>
+<p>
+ Note: This option will be enabled by default in future versions of PageSpeed
+ and eventually the option will be removed entirely.
+</p>
+
+<h2 id="pagespeed_static">Configuring the location of static assets</h2>
+
+<p>
+ Several filters, including <a href="filter-js-defer">defer_javascript</a> and
+ <a href="filter-lazyload-images">lazyload_images</a>, require external
+ resources that must be loaded from somewhere. Before 1.8.31.2,
+ mod_pagespeed would load these files from <code>/mod_pagespeed_static</code>
+ while ngx_pagespeed would load them from <code>/ngx_pagespeed_static</code>.
+ In 1.8.31.2 the default was changed to <code>/pagespeed_static</code> for
+ both platforms and a directive was added to make the path configurable:
+</p>
+<dl>
+ <dt>Apache:
+ <dd><pre class="prettyprint"
+ >ModPagespeedStaticAssetPrefix /custom/static/</pre>
+ <dt>Nginx:
+ <dd><pre class="prettyprint"
+ >pagespeed StaticAssetPrefix /custom/static/;</pre>
+</dl>
+
+<h2 id="add-resource-header">Configuring headers for optimized resources</h2>
+<p>
+ When creating optimized <code>.pagespeed.</code> resources, PageSpeed
+ generates headers that are correct for most users. However, some users
+ require additional headers. For instance if you're
+ using <a
+ href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS</a>
+ and you want to have PageSpeed set <code>Access-Control-Allow-Origin:
+ http://www.example.com</code> headers on the resources it creates, you can
+ set:
+</p>
+<dl>
+ <dt>Apache:
+ <dd><pre class="prettyprint"
+ >ModPagespeedAddResourceHeader "Access-Control-Allow-Origin" "http://www.example.com"</pre>
+ <dt>Nginx:
+ <dd><pre class="prettyprint"
+ >pagespeed AddResourceHeader "Access-Control-Allow-Origin" "http://www.example.com";</pre>
+</dl>
+<p>
+ If you have multiple headers you want inserted you can include
+ an <code>AddResourceHeader</code> directive for each one.
+<p>
+
+<h2 id="ListOutstandingUrlsOnError">List outstanding urls on error</h2>
+<p>
+ When debugging fetching, it can be useful to know how things are failing. If
+ you enable <code>ListOutstandingUrlsOnError</code> then PageSpeed will report
+ a message in the error log at level <code>"error"</code> for every URL fetch
+ in flight when the HTTP stack encounters a system error, e.g. "Connection
+ Refused". To enable this feature, set:
+</p>
+<dl>
+ <dt>Apache:
+ <dd><pre class="prettyprint">ModPagespeedListOutstandingUrlsOnError on</pre>
+ <dt>Nginx:
+ <dd><pre class="prettyprint">pagespeed ListOutstandingUrlsOnError on;</pre>
+</dl>
+
+<h2 id="reverse-proxy">Using PageSpeed as a reverse proxy</h2>
+<p>
+Typically, PageSpeed is used on an Apache or Nginx server that is already
+serving its own content. However, PageSpeed can be used with Nginx or Apache as
+a proxy for another server.
+</p>
+<p>
+With Apache and mod_pagespeed, <a href="http://httpd.apache.org/docs/2.2/mod/mod_proxy.html">
+ mod_proxy</a> can be used to configure Apache as a reverse proxy.
+</p>
+<p>
+With Nginx and ngx_pagespeed, <a href="http://nginx.com/resources/admin-guide/reverse-proxy/">
+ proxy_pass</a> can be used to configure Nginx as a reverse proxy.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/console.html b/doc/console.html
new file mode 100644
index 0000000..fb7b95d
--- /dev/null
+++ b/doc/console.html
@@ -0,0 +1,223 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>PageSpeed Console</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>PageSpeed Console</h1>
+<h2 id="about">About the Console</h2>
+<p>
+ The PageSpeed Console reports various problems your installation has that can
+ lead to sub-optimal performance. The console graphs metrics for these
+ problems over time so that you can see the result of your changes
+ improving or degrading your performance. You can view it by enabling it and
+ then visiting <code>/pagespeed_admin/console</code> from your server. The
+ console works by saving snapshots of the statistics reported by
+ PageSpeed and then using the Google Chart Tools API to graph those
+ statistics over time.
+<h2 id="configuring">Configuring the Console</h2>
+<p>
+ The PageSpeed Console is configured with several directives in the
+ configuration file. See
+ <a href="install#module">PageSpeed Installation and Configuration</a>
+ for details about this file. Each of these directives is explained here.
+</p>
+<ul>
+ <li>
+ <code><a href="admin#statistics">Statistics</a></code>
+ must be enabled to report statistics.</li>
+ <li>
+ <code>StatisticsLogging</code> must be enabled so that graphs of
+ statistics over time can be drawn in the console.</li>
+ <li>
+ <code>LogDir</code> must be set so that we have a directory to store
+ statistic logs.</li>
+ <li>
+ In order to access the console, you must set a handler appropriately.
+ For example, to make the console only accessible from localhost:
+ <dl>
+ <dt>Apache:<dd><pre>
+ModPagespeedStatistics on
+ModPagespeedStatisticsLogging on
+ModPagespeedLogDir /var/log/pagespeed
+<Location /pagespeed_admin>
+ Order allow,deny
+ Allow from localhost
+ Allow from 127.0.0.1
+ SetHandler pagespeed_admin
+</Location></pre>
+ <dt>Nginx:<dd><pre>
+pagespeed Statistics on;
+pagespeed StatisticsLogging on;
+pagespeed LogDir /var/log/pagespeed;
+pagespeed AdminPath /pagespeed_admin;
+
+location ~ ^/pagespeed_admin {
+ allow 127.0.0.1;
+ deny all;
+}</pre>
+ </dl>
+ </li>
+</ul>
+<p>
+ Additionally these optional parameters may be configured:
+</p>
+<ul>
+ <li>
+ <code>StatisticsLoggingIntervalMs</code> may be set to indicate how often
+ to log statistics snapshots (in milliseconds).</li>
+ <li>
+ <code>StatisticsLoggingMaxFileSizeKb</code> may be set to indicate the
+ maximum size for the logfile (in kilobytes).</li>
+</ul>
+<p>
+ For example, to log once a minute with a maximum log size of 1 MB:
+</p>
+<dl>
+ <dt>Apache:<dd><pre>
+ModPagespeedStatisticsLoggingIntervalMs 60000
+ModPagespeedStatisticsLoggingMaxFileSizeKb 1024</pre>
+ <dt>Nginx:<dd><pre>
+pagespeed StatisticsLoggingIntervalMs 60000;
+pagespeed StatisticsLoggingMaxFileSizeKb 1024;</pre>
+</dl>
+
+<h2 id="access">Accessing the Console</h2>
+<p>
+ The console can be accessed by browsing to
+ <code>http://your.example.com/pagespeed_admin/console</code>. Access to
+ this page can be controlled using standard access directives.
+</p>
+<p>
+ Note that if you would like to access the console from machines other
+ than your server, you will need to allow access to
+ <code>/pagespeed_admin</code>.
+</p>
+
+<!-- TODO(sligocki): Add section for features, like zooming in, etc. once we
+ add them. -->
+
+<h2 id="graphs">Graphed metrics</h2>
+The PageSpeed console displays graphs for these metrics:
+<ul>
+ <li id="fetch-failure">
+ <b>Resources not loaded because of fetch failures</b>:
+ Images, CSS or JavaScript could not be loaded because backend HTTP fetch
+ failed. <b>Remedy</b>: You may have to reconfigure your server to allow
+ outgoing connections or to have access to DNS.</li>
+
+ <li id="not-authorized">
+ <b>Resources not rewritten because domain wasn't authorized</b>:
+ Resources could not be rewritten because they were on a different domain
+ than the HTML and that domain was not explicitly authorized.
+ <b>Remedy</b>: Add <a href="domains#auth_domains">Domain</a>
+ authorizations for all domains you control.</li>
+
+ <li id="cache-control">
+ <b>Resources not rewritten because of restrictive Cache-Control headers</b>:
+ Resources could not be rewritten because they had restrictive Cache-Control
+ headers explicitly set (for example: <code>Cache-Control: private</code>,
+ <code>Cache-Control: max-age=0</code> or
+ <code>Cache-Control: no-transform</code>).
+ <b>Remedy</b>: Reconfigure your server to serve these resources with
+ public caching headers (or no Cache-Control headers at all). For example,
+ <code>Header set Cache-Control "max-age=600"</code> in Apache config.</li>
+
+ <li id="cache-miss">
+ <b>Cache misses</b>:
+ Resources were not rewritten because they were not found in cache.
+ This is expected while your cache warms up, soon after you install, however
+ if it continues to be high, your cache is probably too small.
+ <b>Remedy</b>: Increase the
+ <a href="system#file_cache">FileCacheSizeKb</a> to be about 5 times
+ as large as your website content (to store all of the original
+ resources and various versions of rewritten resources).</li>
+
+ <li id="cache-expired">
+ <b>Cache lookups that were expired</b>:
+ Although these resources were found in cache, they were not rewritten
+ because they were older than their max-age.
+ <b>Remedy</b>: (A) Enable
+ <a href="domains#ModPagespeedLoadFromFile">LoadFromFile</a> to tell
+ the server to load the files straight from disk rather than through
+ HTTP. (B) Reconfigure your server to serve resources with longer TTL.
+ For example, <code>Header set Cache-Control "max-age=3600"</code> to set
+ one hour TTL in Apache config.</li>
+
+ <li id="css-error">
+ <b>CSS files not rewritten because of parse errors</b>:
+ CSS files could not be rewritten because our parser found syntax errors
+ that it could not recover from. <b>Remedy</b>: Fix CSS files to use
+ proper syntax. You can use the stand-alone
+ <a href="build_mod_pagespeed_from_source#debug-css">css_minify_main</a>
+ to find what part of the CSS file has parse errors. We have had some
+ problems in the past with valid CSS3 or proprietary CSS extensions
+ causing CSS parsing errors. If you find that your valid CSS is failing to
+ parse, let us know on our <a href="mailing-lists#discussion">discussion
+ group</a> so we can fix the parser.</li>
+
+ <li id="js-error">
+ <b>JavaScript minification failures</b>:
+ JavaScript files could not be minified because our parser found some
+ syntax problem that it could not recover from. This is very uncommon.
+ <b>Remedy</b>: As with CSS, fix the JavaScript files that had problems.</li>
+
+ <li id="image-error">
+ <b>Image rewrite failures</b>:
+ Image files were not rewritten for various reasons:<ul>
+ <li><code>image_norewrites_high_resolution</code>: Image was too large.
+ Currently we only rewrite images below 8 Megapixels.
+ <b>Remedy</b>: Resize original images to a reasonable size.</li>
+ <li><code>image_rewrites_dropped_decode_failure</code>: Image could not
+ be parsed by our code. <b>Remedy</b>: Fix malformed images.</li>
+ <li><code>image_rewrites_dropped_due_to_load</code>: Image was not
+ rewritten because your system was already busy rewriting other images.
+ This generally can happen when you first install PageSpeed
+ while the cache warms up. <b>Remedy</b>: If image rewrites continue
+ to be dropped after a day or so, you may need to
+ <a href="#cache-miss">increase your cache size</a> or increase the
+ <a href="reference-image-optimize#ImageMaxRewritesAtOnce">
+ ImageMaxRewritesAtOnce</a>.</li>
+ <li><code>image_rewrites_dropped_mime_type_unknown</code>: Image could
+ not be rewritten because we do not recognize its MIME-type. For
+ example, we do not parse <code>image/x-icon</code> or
+ <code>image/svg+xml</code>. <b>Remedy</b>: Convert your images to a
+ type that we understand (gif, png, jpg, webp) or perhaps just fix
+ a broken server config that is serving images with a bogus
+ <code>Content-Type</code> header.</li>
+ <li><code>image_rewrites_dropped_server_write_fail</code>: Unexpected
+ server error while rewriting images. If you get a significant number
+ of these write to our <a href="mailing-lists#discussion">discussion
+ group</a> so we can investigate.</li>
+ </ul>
+ </li>
+</ul>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/doc.css b/doc/doc.css
new file mode 100644
index 0000000..e5352cb
--- /dev/null
+++ b/doc/doc.css
@@ -0,0 +1,212 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+body {
+ font-family: sans-serif;
+ margin: 0;
+ padding: 0;
+ line-height: 1.5;
+ word-wrap: break-word;
+}
+
+a {
+ color: #0288d1;
+ text-decoration: none;
+}
+
+a:hover {
+ text-decoration: underline;
+}
+
+#header, #navline {
+ color: white;
+}
+
+#header a, #navline a {
+ color: white;
+}
+
+#logoline {
+ background-color: #0061ff;
+ padding: 1em;
+}
+
+#logo {
+ display: inline-block;
+ position: relative;
+ top: 4px;
+}
+
+#logotext {
+ font-size: 32px;
+ display: inline-block;
+}
+
+#navline a{
+ background-color: #3d87ff;
+ display: block;
+ padding: 0.5em 1em 0.5em 1em;
+}
+
+#content {
+ margin: 0.5em;
+ max-width: 50em;
+}
+
+code, pre {
+ background: #f7f7f7;
+ color: #37474f;
+}
+
+.note, .note code {
+ background: #e1f5fe;
+ color: #0288d1;
+}
+
+.note a {
+ color: #0288d1;
+ text-decoration: underline;
+}
+
+.caution, .caution code {
+ background: #fff3e0;
+ color: #dd2c00;
+}
+
+.caution a {
+ color: #dd2c00;
+ text-decoration: underline;
+}
+
+.warning, .warning code {
+ background: #fbe9e7;
+ color: #d50000;
+}
+
+.warning a {
+ color: #d50000;
+ text-decoration: underline;
+}
+
+.note, .caution, .warning {
+ padding: 1em;
+}
+
+pre {
+ padding: 1em;
+ overflow: auto;
+ line-height: 1.1;
+}
+
+table {
+ margin-top: 1em;
+ margin-bottom: 1em;
+ border-collapse: collapse;
+}
+
+th {
+ color: #fff;
+ vertical-align: middle;
+ background-color: #555;
+}
+
+td {
+ border-top: 1px solid #e0e0e0;
+ background-color: #f7f7f7;
+}
+
+th, td {
+ padding: 1em;
+}
+
+li {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+img {
+ max-width: 100%;
+}
+
+.table-wrapper {
+ max-width: 100%;
+ overflow: auto;
+}
+
+#downloads .download {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+#toc {
+ border-left: 4px solid #0061ff;
+ font-size: 0.9em;
+ max-width: 25em;
+ margin-top: 1em;
+ margin-left: 1em;
+}
+
+#toc-contents {
+ color: #757575;
+ font-weight: bold;
+ padding-left: 1em;
+}
+
+#toc ul {
+ list-style: none;
+ list-style-position: inside;
+ padding-left: 1em;
+}
+
+@media screen and (min-width: 55em) {
+ #toc {
+ float: right;
+ max-width: 18em;
+ padding-right: 1em;
+ }
+}
+
+.header-link {
+ visibility: hidden;
+ font-size: 80%;
+}
+
+h2:hover .header-link,
+h3:hover .header-link,
+h4:hover .header-link,
+h5:hover .header-link,
+h6:hover .header-link {
+ visibility: initial;
+ text-decoration: none;
+}
+
+.column {
+ margin: 0.5em;
+}
+
+.columns {
+ max-width: 75em;
+}
+
+@media screen and (min-width: 50em) {
+ .column {
+ display: inline-block;
+ vertical-align: top;
+ }
+}
diff --git a/doc/domains.html b/doc/domains.html
new file mode 100644
index 0000000..eef8c60
--- /dev/null
+++ b/doc/domains.html
@@ -0,0 +1,1025 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>PageSpeed Authorizing and Mapping Domains</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>PageSpeed Authorizing and Mapping Domains</h1>
+<h2 id="auth_domains">Authorizing domains</h2>
+<p>
+In addition to optimizing HTML resources, PageSpeed restricts itself to
+optimizing resources (JavaScript, CSS, images) that are served from domains,
+with optional paths, that must be explicitly listed in the configuration file.
+For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDomain http://example.com
+ModPagespeedDomain cdn.example.com
+ModPagespeedDomain http://styles.example.com/css
+ModPagespeedDomain *.example.org</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed Domain http://example.com;
+pagespeed Domain cdn.example.com;
+pagespeed Domain http://styles.example.com/css;
+pagespeed Domain *.example.org;</pre>
+</dl>
+
+<p>
+PageSpeed will rewrite resources found from these explicitly
+listed domains, although in the case of <code>styles.example.com</code>
+only resources under the <code>css</code> directory will be rewritten.
+Additionally, it will rewrite resources that are
+served from the same domain as the HTML file, or are specified as
+a path relative to the HTML. When resources are rewritten, their
+domain and path are not changed. However, the leaf name is changed to
+encode rewriting information that can be used to identify and serve
+the optimized resource.
+</p>
+
+<p>The leading "http://" is optional; bare hostnames will be interpreted
+as referring to HTTP. Wildcards can be used in the domain.</p>
+
+<p>
+These directives can be used
+in <a href="configuration#htaccess">location-specific configuration
+sections</a>.
+</p>
+
+
+<h2 id="mapping_origin">Mapping origin domains</h2>
+
+<p>In order to improve the performance of web pages, PageSpeed
+must examine and modify the content of resources referenced on those
+pages. To do that, it must fetch those resources using HTTP, using
+the URL reference specified on the HTML page.</p>
+
+<p>In some cases, the URL specified in the HTML file is not the best URL to use
+to fetch the resource. Scenarios where this is a concern include:</p>
+<ol>
+ <li>If the server is behind a load balancer, and it's more efficient to
+ reference the server directly by its IP address, or as 'localhost'.</li>
+ <li>The server has a special DNS configuration</li>
+ <li>The server is behind a firewall preventing outbound connections</li>
+ <li>The server is running in a CDN or proxy, and must go back to the
+ origin server for the resources</li>
+ <li>The server needs to service https requests</li>
+</ol>
+
+<p>In these situations the remedy is to map the origin domain:</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapOriginDomain origin_to_fetch_from origin_specified_in_html [host_header]</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapOriginDomain origin_to_fetch_from origin_specified_in_html [host_header];</pre>
+</dl>
+
+<p>Wildcards can also be used in the <code>origin_specified_in_html</code>, e.g.
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapOriginDomain localhost *.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapOriginDomain localhost *.example.com;</pre>
+</dl>
+
+<p>The <code>origin_to_fetch_from</code> can include a path after the domain
+name, e.g.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapOriginDomain localhost/example *.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapOriginDomain localhost/example *.example.com;</pre>
+</dl>
+
+<p>When a path is specified, the source domain is mapped to the destination
+domain and the source path is mapped to the concatenation of the path from
+<code>origin_to_fetch_from</code> and the source path. For example, given the
+above mapping, <code>http://www.example.com/index.html</code> will be mapped
+to <code>http://localhost/example/index.html</code>.</p>
+
+<p>The origin_specified_in_html can specify https but the origin_to_fetch_from
+can only specify http, e.g.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapOriginDomain http://localhost https://www.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapOriginDomain http://localhost https://www.example.com;</pre>
+</dl>
+
+<p>This directive lets the server accept https requests for
+<code>www.example.com</code> without requiring a SSL certificate to fetch
+resources. For example, given the above mapping, and assuming the server is
+configured for https support, PageSpeed will fetch and optimize resources
+accessed using
+<code>https://www.example.com</code>, fetching the resources from
+<code>http://localhost</code>, which can be the same server process or a
+different server process.
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapOriginDomain http://localhost https://www.example.com
+ModPagespeedShardDomain https://www.example.com \
+ https://example1.cdn.com,https://example2.cdn.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapOriginDomain http://localhost https://www.example.com;
+pagespeed ShardDomain https://www.example.com
+ https://example1.cdn.com,https://example2.cdn.com;</pre>
+</dl>
+
+<p>In this example the https origin domain is mapped to <code>localhost</code>
+<em>and</em> <a href="domains#shard">sharding</a> is used to parallelize
+downloads across hostnames. Note that the shards also specify https.</p>
+
+<p>By specifying a source domain in this directive, you are authorizing
+PageSpeed to rewrite resources found in that domain. For example, in the
+above directives, '*.example.com' gets authorized for rewrites from HTML files,
+but 'localhost' does not. See <a href="#auth_domains"><code
+>Domain</code></a>.</p>
+
+<p>When PageSpeed fetches resources from a mapped origin domain, it
+specifies the source domain in the <code>Host:</code> header in the
+request. You can override the <code>Host:</code> header value with the
+optional third parameter <code>host_header</code>. See
+<a href="#shared_cdn">Mapping Origins with a Shared Domain</a> for
+an example.</p>
+
+<p>
+ See also
+ <a href="#ModPagespeedLoadFromFile"><code>LoadFromFile</code></a>
+ to load origin resource directly from the filesystem and avoid an HTTP
+ connection altogether.
+</p>
+
+<p>
+These directives can be used
+in <a href="configuration#htaccess">location-specific configuration
+sections</a>.
+</p>
+
+
+<h2 id="mapping_rewrite">Mapping rewrite domains</h2>
+
+<p>When PageSpeed rewrites a resource, it updates the HTML to
+refer to the resource by its new name. Generally PageSpeed leaves
+the resource at the same origin and path that was originally found in
+the HTML. However, it is possible to map the domain of rewritten
+resources. Examples of why this might be desirable include:</p>
+
+<ol>
+ <li>Serving static content from cookieless domains, to reduce the size of
+ HTTP requests from the browser. See
+ <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload">Minimizing Payload</a>
+ <li>To move content to a Content Delivery Network (CDN)</li>
+</ol>
+
+<p>This is done using the configuration file directive:</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapRewriteDomain domain_to_write_into_html \
+ domain_specified_in_html</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapRewriteDomain domain_to_write_into_html
+ domain_specified_in_html;</pre>
+</dl>
+
+<p>Wildcards can also be used in the <code>domain_specified_in_html</code>, e.g.
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapRewriteDomain cdn.example.com *example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapRewriteDomain cdn.example.com *example.com;</pre>
+</dl>
+
+<p>The <code>domain_to_write_into_html</code> can include a path after the
+domain name, e.g.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapRewriteDomain cdn.com/example *.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapRewriteDomain cdn.com/example *.example.com;</pre>
+</dl>
+
+<p>When a path is specified, the source domain is rewritten to the destination
+domain and the source path is rewritten to the concatenation of the path from
+<code>domain_to_write_into_html</code> and the source path. For example, given
+the above mapping, <code>http://www.example.com/index.html</code> will be
+rewritten to <code>http://cdn.com/example/index.html</code>.</p>
+
+<p class="note" id="equiv_servers">
+<strong>Note:</strong> It is the responsibility of the site administrator to
+ensure that PageSpeed is installed on
+the <code>domain_to_write_into_html</code>. This might be a separate server, or
+there may be a single server with multiple domains mapped into it. The files
+must be accessible via the same path on the destination server as was specified
+in the HTML file. No other files should be stored on the
+<code>domain_to_write_into_html</code> -- it should be functionally equivalent
+to <code>domain_specified_in_html</code>. See
+also <a href="#MapProxyDomain">MapProxyDomain</a> which enables proxying content
+from a different server.</p>
+
+<p>For example, if PageSpeed
+cache_extends <code>http://www.example.com/styles/style.css</code> to
+<code>http://cdn.example.com/styles/style.css.pagespeed.ce.HASH.css</code>,
+then <code>cdn.example.com</code> will have to have a mechanism in place to
+either rewrite that file in place, or refer back to the origin server to
+pull the rewritten content.
+</p>
+
+<p class="note">
+<strong>Note:</strong> It is the responsibility of the site
+administrator to ensure that moving resources onto domains does not
+create a security vulnerability. In particular, if the target domain
+has cookies, then any JavaScript loaded from a resource moved to a
+domain with cookies will gain access to those cookies. In general,
+moving resources to a cookieless domain is a great way to improve
+security. Be aware that CSS can load JavaScript in certain environments.
+</p>
+
+<p>By specifying a domain in this directive, either as source or destination,
+you are authorizing PageSpeed to rewrite resources found in this
+domain. See <a href="#auth_domains"><code>Domain</code></a>.</p>
+
+<p>These directives can be used
+in <a href="configuration#htaccess">location-specific configuration
+sections</a>.</p>
+
+<h3 id="shared_cdn">Mapping Origins with a Shared CDN</h3>
+
+<p>Consider a scenario where an installation serving multiple domains
+uses a single CDN for caching and delivery of all content. The origin
+fetches need to be routed to the correct VirtualHost on the server.
+This can be achieved by using a subdirectory per domain in the
+CDN, and then using that subdirectory to map to the correct
+VirtualHost at origin. The host-header control offered by the third
+argument to <a href="#mapping_origin">MapOriginDomain</a> makes this
+feasible.</p>
+
+<p>In the example below, resources with a domain of
+sharedcdn.example.com and path starting with /vhost1 will be fetched
+from localhost but with a <code>Host:</code> header value of
+vhost1.example.com. Without the third argument to MapOriginDomain,
+the <code>Host:</code> header would be sharedcdn.example.com.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapOriginDomain localhost sharedcdn.example.com/vhost1 vhost1.example.com
+ModPagespeedMapRewriteDomain sharedcdn.example.com/vhost1 vhost1.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapOriginDomain localhost sharedcdn.example.com/vhost1 vhost1.example.com;
+pagespeed MapRewriteDomain sharedcdn.example.com/vhost1 vhost1.example.com;</pre>
+</dl>
+
+<p>This would be used in conjunction with a VirtualHost setup for
+vhost1.example.com, and a single CDN setup for multple hosts segregated by
+subdirectory.</p>
+
+<h2 id="shard">Sharding domains</h2>
+
+<p>Best practices suggest <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt"
+>minimizing round-trip times</a> by <a
+ target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt#ParallelizeDownloads"
+>parallelizing downloads across hostnames</a>. PageSpeed can partially
+automate this for resources that it rewrites, using the directive:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedShardDomain domain_to_shard shard1,shard2,shard3...</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ShardDomain domain_to_shard shard1,shard2,shard3...;</pre>
+</dl>
+
+<p>Wildcards cannot be used in this directive.</p>
+
+<p>This will distribute the domains for rewritten URLs among the
+specified shards. The shard selected for a particular URL is computed
+from the original URL.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedShardDomain example.com \
+ static1.example.com,static2.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed ShardDomain example.com static1.example.com,static2.example.com;</pre>
+</dl>
+
+
+<p>
+Using this directive, PageSpeed will distribute roughly half the
+resources rewritten from example.com
+into <code>static1.example.com</code>, and the rest to
+<code>static2.example.com</code>. You can specify as many shards as
+you like. The optimum number of shards is a topic of active
+research, and is browser-dependent. Configuring between 2 and 4
+shards should yield good results. Changing the number of shards
+will cause PageSpeed to choose different names for resources,
+resulting in a partial cache flush.</p>
+
+<p>When used in combination with <code>RewriteDomain</code>, the Rewrite
+mappings will be done first. Then the shard selection occurs. Origin domains
+are always tracked so that when a browser sends a sharded URL back to the
+server, PageSpeed can find it.
+</p>
+<p>Let's look at an example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedShardDomain example.com static1.example.com,static2.example.com
+ModPagespeedMapRewriteDomain example.com www.example.com
+ModPagespeedMapOriginDomain localhost example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed ShardDomain example.com static1.example.com,static2.example.com;
+pagespeed MapRewriteDomain example.com www.example.com;
+pagespeed MapOriginDomain localhost example.com;</pre>
+</dl>
+
+<p>In this example, <code>example.com</code>
+and <code>www.example.com</code> are "tied" together via
+<code>MapRewriteDomain</code>. The origin-mapping
+to <code>localhost</code> propagates automatically
+to <code>www.example.com</code>, <code>static1.example.com</code>, and
+<code>static2.example.com</code>. So when PageSpeed cache-extends an HTML
+stylesheet reference <code>http://www.example.com/styles.css</code>, it will be:
+</p>
+<ol>
+ <li>Fetched by the server rewriting the HTML
+ from <code>localhost</code></li>
+ <li>Rewritten to
+ <code>http://example.com/styles.css.pagespeed.ce.HASH.css</code></li>
+ <li>Sharded to
+ <code>http://static1.example.com/styles.css.pagespeed.ce.HASH.css</code>
+ </li>
+</ol>
+
+<h2 id="MapProxyDomain">Proxying and optimizing resources from
+ trusted domains</h2>
+
+<p>
+ Proxying resources is desirable under several scenarios:
+</p>
+<ul>
+ <li>The resources on the origin domain may benefit from optimizations
+ done by PageSpeed.</li>
+ <li>SPDY may work better if there are fewer domains on a page.</li>
+ <li>The target domain running PageSpeed may have better serving
+ infrastructure than the origin.</li>
+</ul>
+<p>
+ It is possible to proxy and optimize resources whose origin is a trusted
+ domain that may not be running PageSpeed. This cannot be directly achieved
+ with MapRewriteDomain because that is a declaration that the domains listed
+ are functionally equivalent to one another, either because they are backed by
+ the same storage, or because the target is acting as a proxy (e.g. a
+ CDN). <code>MapProxyDomain</code> makes it technically possible to proxy and
+ optimize resources from any domain <b>that you trust</b>.
+
+<p class="warning">
+ You must only proxy resources that are controlled by an organization
+ you <b>trust</b> because it is possible for malicious content (e.g.
+ <a href="http://hackaday.com/2008/08/04/the-gifar-image-vulnerability/"
+ >GIFAR</a>)
+ proxied from an untrustworthy domain to gain access to private
+ content on your domain, compromising your site or its viewers. You
+ must never map directories that may contain files that may be
+ controlled by a third party.
+</p>
+<p class="warning">
+ There may be legal issues restricting the optimization of resources
+ you don't own. If in doubt consult a lawyer.
+ {# TODO(jmarantz): it should be possible to use this directive in #}
+ {# combination with Disallow & rewrite_domains to proxy without #}
+ {# optimizing. A demo/test of that will be left for a follow-up. #}
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedMapProxyDomain target_domain/subdir \
+ origin_domain/subdir [rewrite_domain/subdir]
+</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed MapProxyDomain target_domain/subdir
+ origin_domain/subdir [rewrite_domain/subdir];</pre>
+</dl>
+
+<p>
+If the optional rewrite_domain/subdir argument is supplied then optimized
+resources will be rewritten to that location. This is useful for rewriting
+optimized resources proxied from an external origin to a CDN.
+</p>
+<p>
+ It is important to specify a subdirectory in the target domain, because
+ PageSpeed will need to be able to unambiguously identify the
+ origin domain given the target when fetching content. Thus each
+ MapProxyDomain command should be given a distinct subdirectory
+ of the target domain.
+</p>
+<p>
+ It is important to specify a subdirectory in the origin domain to
+ limit the scope of the proxying. For example,
+ in <a href="https://picasaweb.google.com">picasaweb</a>, all of a user's
+ photos are underneath a single subdirectory; it is critical not to enable
+ proxying for the entire site.
+</p>
+<h3>Example</h3>
+<p>
+You can see proxy-mapping in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/proxy_external_resource.html">example</a>.
+</p>
+
+<h2 id="fetch_servers">Fetch server restrictions</h2>
+ <p> PageSpeed will only fetch resources from <code>localhost</code> and
+ domains explicitly mentioned in domain configuration directives such
+ as <code>Domain</code>, <code>MapRewriteDomain</code>
+ and <code>MapOriginDomain</code>. As this security restriction is not
+ desirable for some large deployments, in Apache it is possible to disable it
+ starting from 0.10.22.7, via the following configuration directive (which has
+ a global effect): <pre class="prettyprint"
+ >ModPagespeedDangerPermitFetchFromUnknownHosts on</pre>
+
+ <p class="warning"><strong>Warning: </strong>Enabling
+ <code>DangerPermitFetchFromUnknownHosts</code> could permit
+ hostile third parties to access any machine and port that the server running
+ mod_pagespeed has access to, including potentially those behind firewalls.
+ </p>
+ Before doing this, however, it must be ensured that at least one of these
+ things is true:
+ <ol>
+ <li>The server running mod_pagespeed has no more access to machines or
+ ports than anyone on the Internet, and that machines it can access will
+ not treat its traffic specially (mod_pagespeed 0.10.22.6 and newer will
+ make sure its own traffic to <code>localhost</code> does not appear to be
+ local, but that does not work across machines)</li>
+ <li>Every virtual host in Apache running mod_pagespeed (and, if applicable,
+ the global configuration) has an accurate explicit <code>ServerName</code>,
+ and sets the options <code>UseCanonicalName</code> and
+ <code>UseCanonicalPhysicalPort</code> to <code>On</code>.
+ <li>A proxy running in front of the mod_pagespeed server fully verifies that
+ the URLs and <code>Host:</code> headers that reach it refer only to machines
+ the mod_pagespeed server is expected to contact.
+ </ol>
+ If possible, you are strongly encouraged to use
+ <code>MapOriginDomain</code> in preference to this switch.
+</p>
+
+<h2 id="url-valued-attributes">Specifying additional URL-valued attributes</h2>
+
+<p>
+ All PageSpeed filters that process URLs need to know which attributes of
+ which elements to consider. By default they consider those in the HTML4 and
+ HTML5 specifications and a few common extensions:
+</p>
+<pre class="prettyprint">
+ <a href=...>
+ <area href=...>
+ <audio src=...>
+ <blockquote cite=...>
+ <body background=...>
+ <button formaction=...>
+ <command icon=...>
+ <del cite=...>
+ <embed src=...>
+ <form action=...>
+ <frame src=...>
+ <html manifest=...>
+ <iframe src=...>
+ <img src=...>
+ <input type="image" src=...>
+ <ins cite=...>
+ <link href=...>
+ <q cite=...>
+ <script src=...>
+ <source src=...>
+ <td background=...>
+ <th background=...>
+ <table background=...>
+ <tbody background=...>
+ <tfoot background=...>
+ <thead background=...>
+ <track src=...>
+ <video src=...>
+</pre>
+<p>
+ If your site uses a non-standard attribute for URLs, PageSpeed won't
+ know to rewrite them or the resources they reference. To identify them to
+ PageSpeed, use the <code>UrlValuedAttribute</code> directive.
+ For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedUrlValuedAttribute span src hyperlink
+ModPagespeedUrlValuedAttribute div background image</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed UrlValuedAttribute span src hyperlink;
+pagespeed UrlValuedAttribute div background image;</pre>
+</dl>
+
+<p>
+ These would identify <code><span src=...></code> and <code><div
+ background=...></code> as containing URLs. Further,
+ the <code>background</code> attribute of <code>div</code> elements would be
+ treated as referring to an image and would be treated just like an image
+ resource referenced with <code><img src=...></code>. The general form
+ is:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedUrlValuedAttribute ELEMENT ATTRIBUTE CATEGORY</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed UrlValuedAttribute ELEMENT ATTRIBUTE CATEGORY;</pre>
+</dl>
+
+<p>
+ All fields are case-insensitive.
+ <span id="categories">Valid categories are:</span>
+ <ul>
+ <li><code>script</code></li>
+ <li><code>image</code></li>
+ <li><code>stylesheet</code> (As of 1.12.34.1)</li>
+ <li><code>otherResource</code>
+ <ul><li>Any other URL that will be automatically loaded by the
+ browser along with the main page. For example,
+ the <code>manifest</code> attribute of the <code>html</code>
+ element or the <code>src</code> attribute of
+ an <code>iframe</code> element.</li></ul>
+ </li>
+ <li><code>hyperlink</code>
+ <ul><li>A link to another page or resource that a browser wouldn't
+ normally load in connection to this page (like
+ the <code>href</code> attribute of an <code>a</code> element).
+ These URLs will still be rewritten
+ by <code>MapRewriteDomain</code> and similar directives, but they
+ will not be sharded and PageSpeed will not load the URL and
+ rewrite the resource.</li></ul>
+ </li>
+ </ul>
+ When in doubt, <code>hyperlink</code> is the safest choice.
+
+<p class="note">
+ <b>Note:</b> Until 1.12.34.1, <code>stylesheet</code> was accepted by the
+ configuration parser, but was non-functional.
+</p>
+
+</p>
+
+<h2 id="ModPagespeedLoadFromFile">Loading static files from disk</h2>
+<p>
+ By default PageSpeed loads sub-resources via an HTTP fetch. It would be
+ faster to load sub-resources directly from the filesystem, however this may
+ not be safe to do because the sub-resources may be dynamically generated or
+ the sub-resources may not be stored on the same server.
+</p>
+<p>
+ However, you can explicitly tell PageSpeed to load static sub-resources from
+ disk by using the <code>LoadFromFile</code> directive. For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile "http://www.example.com/static/" \
+ "/var/www/static/"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile "http://www.example.com/static/"
+ "/var/www/static/";</pre>
+</dl>
+
+<p>
+ tells PageSpeed to load all resources whose URLs start
+ with <code>http://www.example.com/static/</code> from the filesystem
+ under <code>/var/www/static/</code>. For
+ example, <code>http://www.example.com/static/images/foo.png</code> will be
+ loaded from the file <code>/var/www/static/images/foo.png</code>.
+ However, <code>http://www.example.com/bar.jpg</code> will still be fetched
+ using HTTP.
+</p>
+<p>
+ If you need more sophisticated prefix-matching behavior, you can use
+ the <code>LoadFromFileMatch</code> directive, which
+ supports <a href="https://github.com/google/re2/wiki/Syntax">RE2-format</a>
+ regular expressions. (Note that this is not the same format as the wildcards
+ used above and elsewhere in PageSpeed.) For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFileMatch "^https?://example.com/~([^/]*)/static/" \
+ "/var/www/static/\\1"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFileMatch "^https?://example.com/~([^/]*)/static/"
+ "/var/www/static/\\1";</pre>
+</dl>
+
+<p>
+ Will load <code>http://example.com/~pat/static/cat.jpg</code> from
+ <code>/var/www/static/pat/cat.jpg</code>,
+ <code>http://example.com/~sam/static/images/dog.jpg</code> from
+ <code>/var/www/static/sam/images/dog.jpg</code>, and
+ <code>https://example.com/~al/static/css/ie</code> from
+ <code>/var/www/static/al/css/ie</code>. The resource
+ <code>http://example.com/~pat/images/static/puppy.gif</code>, however,
+ would not be matched by this directive and would be fetched using HTTP.
+</p>
+<p>
+ Because PageSpeed is loading the files directly from the filesystem, no custom
+ headers will be set. For example, no headers set with the <code>Header
+ set</code> (Apache) or <code>add_header</code> (Nginx) directives will be
+ applied to these resources. If you have resources that need to be served with
+ custom headers, such as <code>Cache-Control: private</code>, you need to
+ exclude them from <code>LoadFromFile</code>. For resources PageSpeed
+ rewrites <a href="system#ipro">in-place</a> it will set a 5-minute cache
+ lifetime by default, which you can adjust by
+ changing <a href="system#load_from_file_cache_ttl"><code
+ >LoadFromFileCacheTtlMs</code></a>.
+</p>
+<p>
+ Furthermore, the content type will be set based
+ upon only the filename extension and only for common filename extensions we
+ recognize (<code>.html</code>, <code>.css</code>, <code>.js</code>,
+ <code>.jpg</code>, <code>.jpeg</code>, ... see full
+ list: <a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/pagespeed/kernel/http/content_type.cc">content_type.cc</a>).
+ Before 1.9.32.1, filenames with unrecognized extensions were served with no
+ <code>Content-Type</code> header; in 1.9.32.1 and later such filenames will
+ not be loaded from file and instead will fall back to ordinary fetching.
+</p>
+<p>
+ You can also use the <code>LoadFromFile</code> directive to
+ load HTTPS resources which would not be otherwise fetchable directly.
+ For example:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile "https://www.example.com/static/" \
+ "/var/www/static/"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile "https://www.example.com/static/"
+ "/var/www/static/";</pre>
+</dl>
+
+<p>
+ The filesystem path must be an absolute path.
+</p>
+<p>
+ You can specify multiple <code>LoadFromFile</code> associations in
+ configuration files. Note that large numbers of such directives may impact
+ performance.
+</p>
+<p>
+ If the sub-resource cannot be loaded from file in the directory
+ specified, the sub-request will fail (rather than fall back to
+ HTTP fetch). Part of the reason for this is to indicate a configuration
+ error more clearly.
+</p>
+<p>
+ As an added benefit. If resources are loaded from file, the rewritten
+ versions will be updated immediately when you change the associated file.
+ Resources loaded via normal HTTP fetches are refreshed only when they
+ expire from the cache (by default every 5 minutes). Therefore, the
+ rewritten versions are only updated as often as the cache is refreshed.
+ Resources loaded from file are not subject to caching behavior because
+ they are accessed directly from the filesystem for every request for the
+ rewritten version.
+</p>
+
+<p>
+ See also <a href="#mapping_origin"><code>MapOriginDomain</code></a>.
+</p>
+
+<p>
+ This directive can <strong>not</strong> be used
+ in <a href="configuration#htaccess">location-specific configuration
+ sections</a>.
+</p>
+
+<h4 id="limiting-load-from-file">Limiting Direct Loading</h4>
+<p>
+ A mapping set up with <code>LoadFromFile</code> allows filesystem loading for
+ anything it matches. If you have directories or file types that cannot be
+ loaded directly from the filesystem, <code>LoadFromFileRule</code> lets you
+ add fine-grained rules to control which files will be loaded directly and
+ which will fall back to the standard process, over HTTP.
+</p>
+<p>
+ When given a URL PageSpeed first determines whether any LoadFromFile
+ mappings apply. If one does, it calculates the mapped filename and checks for
+ applicable LoadFromFileRules. Considering rules in the reverse order of
+ definition, it takes the first applicable one and uses that to determine
+ whether to load from file or fall back to HTTP.
+</p>
+<p>
+ Some examples may be helpful. Consider a website that is entirely static
+ content except for a <code>/cgi-bin</code> directory:
+</p>
+<pre>
+ /var/www/index.html
+ /var/www/pets.html
+ /var/www/images/cat.jpg
+ /var/www/stylesheets/main.css
+ /var/www/stylesheets/ie.css
+ /var/www/cgi-bin/guestbook.pl
+ /var/www/cgi-bin/visitcounter.pl
+</pre>
+<p>
+ While most of the site can be loaded directly from the
+ filesystem, <code>guestbook.pl</code> and <code>visitcounter.pl</code> are
+ perl files that need to be interpreted before serving. Adding a rule
+ disallowing the <code>/cgi-bin</code> directory tells us to fall back to HTTP
+ appropriately:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile http://example.com/ /var/www/
+ModPagespeedLoadFromFileRule Disallow /var/www/cgi-bin/</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile http://example.com/ /var/www/;
+pagespeed LoadFromFileRule Disallow /var/www/cgi-bin/;</pre>
+</dl>
+
+<p>
+ The <code>LoadFromFileRule</code> directive takes two arguments.
+ The first must be either <code>Allow</code> or <code>Disallow</code> while the
+ second is a prefix that specifies which filesystem paths it should apply to.
+ Because the default is to allow loading from the filesystem for all paths
+ listed in any <code>LoadFromFile</code> statement, most of the time you will
+ be using <code>Disallow</code> to turn off filesystem loading for some subset
+ of those paths. You would use <code>Allow</code> only after
+ a <code>Disallow</code> that was overly general.
+</p>
+<p>
+ Not all sites are well suited for prefix-based control. Consider a site with
+ PHP files mixed in with ordinary static files:
+</p>
+<pre>
+ /var/www/index.html
+ /var/www/webmail.php
+ /var/www/webmail.css
+ /var/www/blog/index.php
+ /var/www/blog/header.png
+ /var/www/blog/blog.css
+</pre>
+<p>
+ Blacklisting just the <code>.php</code> files so they fall back to an HTTP
+ fetch allows everything else to be loaded directly from the filesystem:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile http://example.com/ /var/www/
+ModPagespeedLoadFromFileRuleMatch Disallow \.php$</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile http://example.com/ /var/www/;
+pagespeed LoadFromFileRuleMatch Disallow \.php$;</pre>
+</dl>
+
+<p>
+ The <code>LoadFromFileRuleMatch</code> directive also takes two arguments.
+ The first is either <code>Allow</code> or <code>Disallow</code> and functions
+ just like for <code>LoadFromFileRule</code> above. The second argument,
+ however, is
+ a <a href="https://github.com/google/re2/wiki/Syntax">RE2-format</a> regular
+ expression instead of a file prefix. Remember to escape characters that have
+ special meaning in regular expressions. For example, if instead
+ of <code>\.php$</code> we had simply <code>.php$</code> then a file
+ named <code>example.notphp</code> would still be forced to load over HTTP
+ because "<code>.</code>" is special syntax for "match any single character".
+</p>
+<p>
+ Consider a site with the opposite problem: a few file types can be reliably
+ loaded from file but the rest need interpretation first. For example:
+</p>
+<pre>
+ /var/www/index.html
+ /var/www/site.css
+ /var/www/script-using-ssi.js
+ /var/www/generate-image.pl
+ /var/www/
+</pre>
+<p>
+ This site uses server side includes
+ (<a href="http://httpd.apache.org/docs/2.2/howto/ssi.html">Apache</a>,
+ <a href="http://wiki.nginx.org/HttpSsiModule">Nginx</a>)
+ in its javascript and <code>generate-image.pl</code> needs to be interpreted
+ to make images. The only resources on the site that are generally safe to
+ load are <code>.css</code> ones. By first blacklisting everything and then
+ whitelisting only the <code>.css</code> files, we can make PageSpeed do this:
+</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLoadFromFile http://example.com/ /var/www/
+ModPagespeedLoadFromFileRuleMatch disallow .*
+ModPagespeedLoadFromFileRuleMatch allow \.css$</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed LoadFromFile http://example.com/ /var/www/;
+pagespeed LoadFromFileRuleMatch disallow .*;
+pagespeed LoadFromFileRuleMatch allow \.css$;</pre>
+</dl>
+
+<p>
+ This works because order is significant: later rules take precedence over
+ earlier ones.
+</p>
+
+<h3 id="LoadFromFileScriptVariables">Script Variables with LoadFromFile</h3>
+<p class="note"><strong>Note: New feature as of 1.9.32.1</strong></p>
+<p class="note"><strong>Note: Nginx-only</strong></p>
+
+<p>
+ As of 1.9.32.1 Nginx <a href="http://nginx.org/en/docs/varindex.html">script
+ variables</a> are now supported with the various <code>LoadFromFile</code>
+ directives. Script support for those options makes it possible to configure a
+ generic mapping of http hosts to disk, to reduce the amount of configuration
+ required when you want to load as much from disk as possible but have a lot
+ of <code>server{}</code> blocks.
+</p>
+
+<p>
+ As an example, consider one server that hosts three sites, each of which have
+ a directory <code>/static</code> that holds static resources and can be loaded
+ from file. One way to configure this server would be:
+</p>
+
+<dl>
+ <dt>Nginx:<dd><pre class="prettyprint">
+http {
+ ...
+ server {
+ server_name a.example.com;
+ pagespeed LoadFromFile http://a.example.com/static /var/www-a/static;
+ ...
+ }
+ server {
+ server_name b.example.com;
+ pagespeed LoadFromFile http://b.example.com/static /var/www-b/static;
+ ...
+ }
+ server {
+ server_name c.example.com;
+ pagespeed LoadFromFile http://c.example.com/static /var/www-c/static;
+ ...
+ }
+}</pre>
+</dl>
+
+<p>
+ For three sites this is kind of annoying, but the more sites you have the
+ worse it gets. With <code>ProcessScriptVariables</code> you can define one
+ generic <code>LoadFromFile</code> mapping instead of defining each one
+ individually:
+</p>
+
+<dl>
+ <dt>Nginx:<dd><pre class="prettyprint">
+http {
+ ...
+ pagespeed ProcessScriptVariables on;
+ pagespeed LoadFromFile "http://$host/static" "$document_root/static";
+
+ server {
+ server_name a.example.com;
+ ...
+ }
+ server {
+ server_name b.example.com;
+ ...
+ }
+ server {
+ server_name c.example.com;
+ ...
+ }
+}</pre>
+</dl>
+
+<p>
+ This will use Nginx's <code>$host</code> and <code>$document_root</code>
+ script variables instead of requiring you to explicitly code each one.
+</p>
+
+<p>
+ For more details on script variables, including how to handle dollar signs,
+ see <a href="system#nginx_script_variables">Script Variable Support</a>.
+</p>
+
+<h3 id="risks">Risks</h3>
+<p>
+ This should only be used for completely static resources which do not
+ need any custom headers or special server processing. If non-static
+ resources exist in the specified directory, the source code will
+ be used without applying SSI includes, CGI generation, etc.
+ Furthermore, all the resources should have filenames with common
+ extensions for their Content-Type (Ex: .html, .css, .js, .jpg, .jpeg, ... see
+ full list: <a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/pagespeed/kernel/http/content_type.cc">content_type.cc</a>).
+</p>
+
+<h2 id="inline_without_auth">Inlining resources without explicit authorization
+</h2>
+<p>
+ Several filters in PageSpeed operate by inlining content from resources into
+ the HTML: inline_css, inline_javascript and prioritize_critical_css are a
+ few of the filters that operate in this manner. If resources from
+ third-party domains are not authorized explicitly, the effectiveness of
+ these filters decreases. For instance, prioritize_critical_css attempts to
+ remove blocking CSS requests needed for the initial render by inlining
+ critical CSS snippets into the HTML, however, the CSS resources that are not
+ authorized will continue to block. This option allows such resources to
+ be inlined without having to authorize all the individual domains.
+</p>
+<p>
+ The <code>InlineResourcesWithoutExplicitAuthorization</code>
+ directive can be used to allow resources from third-party domains to be
+ inlined into the HTML without requiring explicit authorization for each
+ domain. This option is "off" by default, and takes a
+ comma-separated list of strings representing resource categories for which
+ the option should be enabled. The list of valid resource categories is
+ given <a href="#categories">here</a>. Currently, only Script and
+ Stylesheet resource types are supported for this option.
+</p>
+
+This option can be enabled as follows:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedInlineResourcesWithoutExplicitAuthorization Script,Stylesheet
+</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed InlineResourcesWithoutExplicitAuthorization Script,Stylesheet;
+</pre>
+</dl>
+
+ <p class="warning"><strong>Warning: </strong>Enabling
+ <code>InlineResourcesWithoutExplicitAuthorization</code> could permit
+ hostile third parties to access any machine and port that the server running
+ mod_pagespeed has access to, including potentially those behind firewalls.
+ Please read the following information for details.
+ </p>
+<p>
+ This directive should only be enabled if all of the following conditions are
+ met for the resource types for which this option is enabled:
+</p>
+<ol>
+<li>The webmaster is confident that the resources referenced on their pages are
+ from trusted domains only.
+</li>
+<li>The site does not allow user-injected resources for the enabled resource
+ types.
+</li>
+<li>Fetches from the PageSpeed server should have no
+ more access to machines or ports than anyone on the Internet, and machines it
+ can access should not treat its traffic specially. Specifically, the
+ PageSpeed servers should not be able to access anything that is internal to a
+ firewall. Please refer to <a href="#fetch_servers">
+ Fetch server restrictions</a> sections for more details.
+</li>
+</ol>
+
+<p>
+ Note that resources inlined into HTML via this option will not be accessible
+ directly via a pagespeed URL, since that involves different security risks.
+ Resources will also not be inlined into other non-HTML resources via this
+ option. This means that flatten_css_imports will not flatten third-party CSS
+ into another CSS resource, unless the relevant third-party domains are
+ authorized explicitly via one of the techniques mentioned in the previous
+ sections.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/download.html b/doc/download.html
new file mode 100644
index 0000000..1b601f8
--- /dev/null
+++ b/doc/download.html
@@ -0,0 +1,133 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Installing From Packages</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Installing From Packages</h1>
+<p class="note">
+ If you're using Nginx you need
+ to <a href="build_ngx_pagespeed_from_source">build from source</a>. These
+ packages are Apache-only.
+</p>
+<p class="note">
+ Any releases offered here are pre-apache releases. The incubating project
+ is working to produce its first release.
+</p>
+
+<div id="downloads">
+<dl>
+ <dt>Latest Beta Version</dt>
+ <dd>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-beta_current_i386.deb">mod_pagespeed 32-bit .deb (Debian/Ubuntu)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-beta_current_amd64.deb">mod_pagespeed 64-bit .deb (Debian/Ubuntu)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-beta_current_i386.rpm">mod_pagespeed 32-bit .rpm (CentOS/Fedora)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-beta_current_x86_64.rpm">mod_pagespeed 64-bit .rpm (CentOS/Fedora)</a></div>
+ </dd>
+ <dt>Latest Stable Version</dt>
+ <dd>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_i386.deb">mod_pagespeed 32-bit .deb (Debian/Ubuntu)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_amd64.deb">mod_pagespeed 64-bit .deb (Debian/Ubuntu)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_i386.rpm">mod_pagespeed 32-bit .rpm (CentOS/Fedora)</a></div>
+<div class=download><a href="https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_x86_64.rpm">mod_pagespeed 64-bit .rpm (CentOS/Fedora)</a></div>
+ </dd>
+</dl>
+</div>
+
+<h3>Supported platforms</h3>
+<ul>
+<li>CentOS/Fedora (32-bit and 64-bit)</li>
+<li>Debian/Ubuntu (32-bit and 64-bit)</li>
+</ul>
+
+<p>To install the packages, on Debian/Ubuntu, please run the following
+command:</p>
+<pre class="prettyprint lang-bsh">
+sudo dpkg -i mod-pagespeed-*.deb
+sudo apt-get -f install
+</pre>
+
+<p>For CentOS/Fedora, please execute:</p>
+<pre class="prettyprint">
+sudo yum install at # if you do not already have 'at' installed
+sudo rpm -U mod-pagespeed-*.rpm
+</pre>
+
+<p>Installing mod_pagespeed will add the Google repository so your system
+will automatically keep mod_pagespeed up to date. If you don't want Google's
+repository, do <code>sudo touch /etc/default/mod-pagespeed</code> before
+installing the package.</p>
+
+<p>You can also download a number of <a href="https://dl-ssl.google.com/page-speed/mod-pagespeed/mod_pagespeed_examples.tar.gz">system tests</a>. These are the same tests available on <a href="http://www.modpagespeed.com">ModPageSpeed.com</a>.</p>
+
+<h3>What is installed</h3>
+<ul>
+<li>The mod_pagespeed packages install two versions of the mod_pagespeed code
+itself, <code>mod_pagespeed.so</code> for Apache 2.2
+and <code>mod_pagespeed_ap24.so</code> for Apache 2.4.</li>
+<li>Configuration files: <code>pagespeed.conf</code>, <code>pagespeed_libraries.conf</code>, and (on Debian) <code>pagespeed.load</code>. If you modify one of these configuration files, that file will not be upgraded automatically in the future.</li>
+<li>A standalone JavaScript minifier <code>pagespeed_js_minify</code> based on
+the one used in mod_pagespeed, that can
+both <a href="build_from_source#js-minify">minify JavaScript</a>
+and <a href="filter-canonicalize-js#sample">generate metadata for library
+canonicalization</a>. </li>
+</ul>
+
+<h2>How to upgrade</h2>
+<p>To upgrade from a previous version, use the standard <code>yum</code> or
+<code>apt-get</code> update commands. For example:</p>
+<dl>
+ <dt>.rpm
+ <dd><pre>
+sudo yum update mod-pagespeed-beta # Or mod-pagespeed-stable
+sudo /etc/init.d/httpd restart</pre>
+ <dt>.deb
+ <dd><pre>
+sudo apt-get update
+sudo apt-get upgrade
+sudo /etc/init.d/apache2 restart</pre>
+</dl>
+
+<h2>How to Change Channels</h2>
+<p>To convert from one channel to another, uninstall one and re-install
+the other. For example, if you would like to move from stable to beta
+channel:</p>
+<dl>
+ <dt>.rpm
+ <dd><pre>
+sudo yum remove mod-pagespeed-stable
+sudo yum install mod-pagespeed-beta</pre>
+ <dt>.deb
+ <dd><pre>
+sudo apt-get remove mod-pagespeed-stable
+sudo apt-get install mod-pagespeed-beta</pre>
+</dl>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/downstream-caching.html b/doc/downstream-caching.html
new file mode 100644
index 0000000..179e43b
--- /dev/null
+++ b/doc/downstream-caching.html
@@ -0,0 +1,521 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Configuring Downstream Caches</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Configuring Downstream Caches</h1>
+<style>
+.diff-del { color: darkred }
+.diff-add { color: green }
+</style>
+
+<h2 id="standard">Standard Configuration</h2>
+ <p class="warning"><strong>Note: This feature is currently experimental.
+ Options and configuration described here are subject to change in future
+ releases. Please subscribe to the <a href="mailing-lists#announcements"
+ >announcements mailing list</a> to keep yourself informed of updates to
+ this feature.</strong></p>
+
+ <p>
+ By default PageSpeed serves HTML files with <code>Cache-Control: no-cache,
+ max-age=0</code> so that changes to the HTML and its resources are sent
+ fresh on each request. The HTML can be cached, however, if you:
+ <ul>
+ <li> Set up a <code>PURGE</code> handler in your cache.
+ <li> Tell PageSpeed the url for the <code>PURGE</code> handler.
+ <li> Have the cache set the <code>PS-CapabilityList</code> header
+ so PageSpeed will emit HTML that can be sent to any browser.
+ <li> Have the cache occasionally pass through requests to the origin with
+ the <code>PS-ShouldBeacon</code> header set.
+ </ul>
+ </p>
+
+ <p>
+ For example, if you're running a cache on port 80 that reverse proxies to
+ your site on port 8080, then you'd need to tell PageSpeed to send
+ its <code>PURGE</code> requests to port 80:
+ </p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDownstreamCachePurgeLocationPrefix http://localhost:80</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed DownstreamCachePurgeLocationPrefix http://localhost:80;</pre>
+</dl>
+ <p>
+ You also need to give PageSpeed a key so it can allow the cache to request
+ rebeaconing without allowing external entities to do so:
+ </p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDownstreamCacheRebeaconingKey "<your-secret-key>"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed DownstreamCacheRebeaconingKey "<your-secret-key>";</pre>
+</dl>
+ <p>
+ These are the only changes you need to make to the PageSpeed configuration
+ file, but before you restart you also need to make some changes to your
+ cache configuration. These vary by cache; below are configurations for
+ Varnish 3.x, Varnish 4.x, and Nginx's proxy_cache:
+ </p>
+<dl>
+ <dt>Varnish 3.x:<dd><pre class="prettyprint">
+acl purge {
+ # If PageSpeed isn't running on the same server as your cache, list the IP(s)
+ # of the PageSpeed machine(s) here.
+ "127.0.0.1";
+}
+sub vcl_recv {
+ # Tell PageSpeed not to use optimizations specific to this request.
+ set req.http.PS-CapabilityList = "fully general optimizations only";
+
+ # Don't allow external entities to force beaconing.
+ remove req.http.PS-ShouldBeacon;
+
+ # Authenticate the purge request by IP.
+ if (req.request == "PURGE") {
+ if (!client.ip ~ purge) {
+ error 405 "Not allowed.";
+ }
+ return (lookup);
+ }
+}
+
+# Mark HTML as uncacheable. If we can't send them purge requests they can't
+# cache our html.
+sub vcl_fetch {
+ if (beresp.http.Content-Type ~ "text/html") {
+ remove beresp.http.Cache-Control;
+ set beresp.http.Cache-Control = "no-cache, max-age=0";
+ }
+ return (deliver);
+}
+
+sub vcl_hit {
+ # Make purging happen in response to a PURGE request. This happens
+ # automatically in Varnish 4.x so we don't need it there.
+ if (req.request == "PURGE") {
+ purge;
+ error 200 "Purged.";
+ }
+
+ # 5% of the time ignore that we got a cache hit and send the request to the
+ # backend anyway for instrumentation.
+ if (std.random(0, 100) < 5) {
+ set req.http.PS-ShouldBeacon = "<your-secret-key>";
+ return (pass);
+ }
+}
+
+sub vcl_miss {
+ # Make purging happen in response to a PURGE request. This happens
+ # automatically in Varnish 4.x so we don't need it there.
+ if (req.request == "PURGE") {
+ purge;
+ error 200 "Purged.";
+ }
+
+ # Instrument 25% of cache misses.
+ if (std.random(0, 100) < 25) {
+ set req.http.PS-ShouldBeacon = "<your-secret-key>";
+ return (pass);
+ }
+}</pre>
+ <dt>Varnish 4.x:<dd><pre class="prettyprint">
+acl purge {
+ # If PageSpeed isn't running on the same server as your cache, list the IP(s)
+ # of the PageSpeed machine(s) here.
+ "127.0.0.1";
+}
+
+sub vcl_recv {
+ # Tell PageSpeed not to use optimizations specific to this request.
+ set req.http.PS-CapabilityList = "fully general optimizations only";
+
+ # Don't allow external entities to force beaconing.
+ unset req.http.PS-ShouldBeacon;
+
+ # Authenticate the purge request by IP.
+ if (req.method == "PURGE") {
+ if (!client.ip ~ purge) {
+ return (synth(405,"Not allowed."));
+ }
+ return (purge);
+ }
+}
+
+# Mark HTML as uncacheable. If we can't send them purge requests they can't
+# cache our html.
+sub vcl_backend_response {
+ if (beresp.http.Content-Type ~ "text/html") {
+ unset beresp.http.Cache-Control;
+ set beresp.http.Cache-Control = "no-cache, max-age=0";
+ }
+ return (deliver);
+}
+
+sub vcl_hit {
+ # 5% of the time ignore that we got a cache hit and send the request to the
+ # backend anyway for instrumentation.
+ if (std.random(0, 100) < 5) {
+ set req.http.PS-ShouldBeacon = "<your-secret-key>";
+ return (pass);
+ }
+}
+sub vcl_miss {
+ # Instrument 25% of cache misses.
+ if (std.random(0, 100) < 25) {
+ set req.http.PS-ShouldBeacon = "<your-secret-key>";
+ return (pass);
+ }
+}</pre>
+ <dt>Nginx proxy_cache:<dd><pre class="prettyprint">
+http {
+ # Define a mapping used to mark HTML as uncacheable.
+ map $upstream_http_content_type $new_cache_control_header_val {
+ default $upstream_http_cache_control;
+ "~*text/html" "no-cache, max-age=0";
+ }
+
+ server {
+ # PageSpeed's beacon dependent filters need the cache to let some requests
+ # through to the backend. This code below depends on the <a href="http://wiki.nginx.org/HttpSetMiscModule">ngx_set_misc</a>
+ # module and randomly passes 5% of traffic to the backend for rebeaconing.
+ set $should_beacon_header_val "";
+ set_random $rand 0 100;
+ if ($rand ~* "^[0-4]$") {
+ set $should_beacon_header_val "<your-secret-key>";
+ set $bypass_cache 1;
+ }
+
+ location / {
+ # existing proxy_pass
+ # existing proxy_cache
+ # existing proxy_cache_key
+
+ # What servers should we accept PURGE requests from? If PageSpeed isn't
+ # running on the same server as your cache, list the IP(s) of the
+ # PageSpeed machine(s) here.
+ #
+ # This requires rebuilding with the ngx_cache_purge module:
+ # https://github.com/FRiCKLE/ngx_cache_purge
+ proxy_cache_purge PURGE from 127.0.0.1;
+
+ # Mark HTML as uncacheable. If we can't send them purge requests they
+ # can't cache our html. Uses the map defined above.
+ proxy_hide_header Cache-Control;
+ add_header Cache-Control $new_cache_control_header_val;
+
+ # Tell PageSpeed not to use optimizations specific to this request.
+ proxy_set_header PS-CapabilityList "fully general optimizations only";
+
+ # See discussion of rebeaconing above.
+ proxy_cache_bypass $bypass_cache;
+ proxy_hide_header PS-ShouldBeacon;
+ proxy_set_header PS-ShouldBeacon $should_beacon_header_val;
+ }
+ }
+}</pre>
+</dl>
+
+<p>
+ When running with downstream caching all resources referenced from the HTML
+ will be cache-extended as usual, so if you have resources that need to be
+ cached for a short time then they can be stale. If so,
+ either <code>Disallow</code> those resources, so PageSpeed doesn't inline or
+ cache-extend them, or decrease the cache lifetime on your HTML.
+</p>
+
+<h2 id="additional">Additional Options</h2>
+
+The configuration above should be a good fit for most sites, but PageSpeed's
+downstream caching is highly configurable with many options that allow you to
+tweak it for your particular setup.
+
+<h3 id="beaconing">Beaconing</h3>
+<p>
+ Several filters such as
+ <a href="reference-image-optimize#inline_images">inline_images</a>,
+ <a href="filter-inline-preview-images">inline_preview_images</a>,
+ <a href="filter-lazyload-images">lazyload_images</a> and
+ <a href="filter-prioritize-critical-css">prioritize_critical_css</a>
+ depend extensively on client beacons to determine critical images and
+ CSS. When such filters are enabled, pages periodically have beaconing
+ JavaScript inserted as part of the rewriting process.
+ The <a href="#standard">standard configuration</a> passes through 5% of cache
+ hits to the backend with a <code>PS-ShouldBeacon</code> header set, so that
+ these filters can continue to receive the beacons they need.
+</p>
+<p>
+ If you have a high traffic site, 5% is probably a larger share than you need
+ for PageSpeed to receive sufficient beacons. In that case you can decrease
+ the percentage of traffic to pass through. For example, here's how you'd
+ decrease it to 2%:
+</p>
+<dl>
+ <dt>Varnish 3.x or 4.x:<dd><pre>
+<span class=diff-del>- if (std.random(0, 100) < 5) {</span>
+<span class=diff-add>+ if (std.random(0, 100) < 2) {</span></pre>
+ <dt>Nginx proxy_cache<dd><pre>
+<span class=diff-del>- if ($rand ~* "^[0-4]$") {</span>
+<span class=diff-add>+ if ($rand ~* "^[01]$") {</span></pre>
+</dl>
+<p>
+ Alternatively, you may be willing to give up the benefit of the
+ beaconing-dependent filters in exchange for never intentionally bypassing the
+ cache. If so, you should <a href="config_filters#beacons">turn off
+ beaconing</a> and beacon-dependent filters in PageSpeed:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+>ModPagespeedCriticalImagesBeaconEnabled false
+ModPagespeedDisableFilters prioritize_critical_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+>pagespeed CriticalImagesBeaconEnabled false;
+pagespeed DisableFilters prioritize_critical_css;</pre>
+</dl>
+<p>
+ Additionally you should remove the proxy config that handles beaconing:
+</p>
+<dl>
+ <dt>Varnish 3.x:<dd><pre><span class="diff-del"
+>- remove req.http.PS-ShouldBeacon;
+...
+- if (std.random(0, 100) < 5) {
+- set req.http.PS-ShouldBeacon = "<your-secret-key>";
+- return (pass);
+- }
+...
+- if (std.random(0, 100) < 25) {
+- set req.http.PS-ShouldBeacon = "<your-secret-key>";
+- return (pass);
+- }</span></pre>
+ <dt>Varnish 4.x:<dd><pre><span class="diff-del"
+>- unset req.http.PS-ShouldBeacon;
+...
+- sub vcl_hit {
+- if (std.random(0, 100) < 5) {
+- set req.http.PS-ShouldBeacon = "<your-secret-key>";
+- return (pass);
+- }
+- }
+- sub vcl_miss {
+- if (std.random(0, 100) < 25) {
+- set req.http.PS-ShouldBeacon = "<your-secret-key>";
+- return (pass);
+- }
+- }</span></pre>
+ <dt>Nginx proxy_cache<dd><pre><span class="diff-del"
+>- set $should_beacon_header_val "";
+- set_random $rand 0 100;
+- if ($rand ~* "^[0-4]$") {
+- set $should_beacon_header_val "<your-secret-key>";
+- set $bypass_cache 1;
+- }
+...
+- proxy_cache_bypass $bypass_cache;
+- proxy_hide_header PS-ShouldBeacon;
+- proxy_set_header PS-ShouldBeacon $should_beacon_header_val;</span></pre>
+</dl>
+
+
+<h3 id="ps-resource">PageSpeed Resources</h3>
+<p>
+ Because PageSpeed already caches its optimized resources, you may want to
+ exclude them caching by the downstream cache. If so, you can set:
+
+<dl>
+ <dt>Varnish 3.x and 4.x:<dd><pre><span class="diff-add"
+>+ if (req.url ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+") {
++ return (pass);
++ }</span></pre>
+ <dt>Nginx proxy_cache<dd><pre><span class="diff-add"
+>+ if ($uri ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+") {
++ set $bypass_cache "1";
++ }</span></pre>
+</dl>
+
+<p>
+ If you have enabled <a href="restricting_urls#url_signatures">URL signing</a>,
+ change the <code>10</code> in the regexp to <code>20</code> to account for the
+ additional characters in the hash.
+</p>
+
+<h3 id="ps-capabilitylist">PS-CapabilityList</h3>
+
+<p>
+ Typically PageSpeed will produce different HTML for different browsers. For
+ example, when responding to a request that has <code>Accept:
+ image/webp</code>, PageSpeed knows the requesting browser supports WebP and so
+ it can send these images, while if the <code>Accept</code> header doesn't
+ mention WebP then it will send JPEG or PNG. To suppress this behavior,
+ the <a href="#standard">standard configuration</a> above sets a header:
+</p>
+<pre>
+ PS-CapabilityList: fully general optimizations only
+</pre>
+<p>
+ This header can also be used to tell PageSpeed to make specific optimizations.
+ There are five capabilities PageSpeed can take advantage of that aren't
+ supported in all browsers, and it gives them each a code:
+</p>
+<table>
+ <tr><th>Capability<th>Code
+ <tr><td>Inline Images<td><code>ii</code>
+ <tr><td>Lazyload Images<td><code>ll</code>
+ <tr><td>WebP Images<td><code>jw</code>
+ <tr><td>Lossless WebP Images<td><code>ws</code>
+ <tr><td>Animated WebP Images<td><code>wa</code>
+ <tr><td>Defer Javascript<td><code>dj</code>
+</table>
+<p>
+ For example, you could include whether the <code>Accept</code> header
+ includes <code>image/webp</code> in your cache key, and then for the
+ fraction of traffic that claimed webp support send:
+</p>
+<pre>
+ PS-CapabilityList: jw:
+</pre>
+<p>
+ Every page would go through to your origin twice and be cached twice, once
+ processed with WebP support and once without.
+</p>
+<p>
+ You can combine multiple capabilities together with a comma. For example, if
+ you decided to make a cache fragment for Chrome 30+, which supports all of
+ these, for that fragment you would send:
+</p>
+<pre>
+ PS-CapabilityList: ll,ii,dj,jw,ws:
+</pre>
+<p>
+ For Firefox 4+, which supports all of these but WebP, you would send:
+</p>
+<pre>
+ PS-CapabilityList: ll,ii,dj:
+</pre>
+<p>
+ To use this header properly, however, you have to know which capabilities are
+ supported by which browsers in the version of PageSpeed you're using and craft
+ regular expressions to match exactly those ones. This is very difficult to do
+ in general because it involves duplicating the code in
+ <a href="https://github.com/apache/incubator-pagespeed-mod/blob/latest-stable/pagespeed/kernel/http/user_agent_matcher.cc"><code>user_agent_matcher.cc</code></a>
+ as regexes, but a simple division is:
+ <ul>
+ <li>Chrome 32+: <code>ll,ii,dj,jw,wa,ws</code>
+ <li>Firefox 4+, Safari, IE10 (but not IE11): <code>ll,ii,dj</code>
+ <li>Everything else: <code>fully general optimizations only</code>
+ </ul>
+</p>
+
+<h3 id="purge-get">Purging with GET</h3>
+
+<p>
+ If you're integrating PageSpeed with a cache that doesn't
+ support <code>PURGE</code> requests but does support purging in response to a
+ prefixed <code>GET</code> request, PageSpeed can support that. You would
+ configure your cache to treat a <code>GET</code> to
+ <code>/purge/foo/bar</code> as a request to purge <code>/foo/bar</code> and
+ configure PageSpeed as:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDownstreamCachePurgeLocationPrefix http://CACHE-HOST:PORT/purge
+ModPagespeedDownstreamCachePurgeMethod GET</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed DownstreamCachePurgeLocationPrefix http://CACHE-HOST:PORT/purge;
+pagespeed DownstreamCachePurgeMethod GET;</pre>
+</dl>
+
+<h3 id="purge-threshold">Purge Threshold</h3>
+<p>
+ Whenever PageSpeed serves an HTML response that is not fully optimized it
+ continues rewriting in the background. When it finishes, if the HTML it
+ served was less than 95% optimized, it sends a purge request to the downstream
+ cache. The next request to come in will bypass the cache and come back to
+ PageSpeed where it can serve out the now more highly optimized page. If you
+ want to change what point PageSpeed considers the page done and stops
+ optimizing, you can set a different value for this threshold. For example, to
+ lower it to 80%, so that PageSpeed is satisfied with a page that is only 80%
+ optimized, you would set:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedDownstreamCacheRewrittenPercentageThreshold 80</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed DownstreamCacheRewrittenPercentageThreshold 80;</pre>
+</dl>
+
+<h3 id="script-variables">Script Variables</h3>
+<p class="note"><strong>Note: Nginx-only</strong></p>
+<p class="note"><strong>Note: New feature as of 1.10.33.0</strong></p>
+
+<p>
+ In ngx_pagespeed <code>DownstreamCachePurgeLocationPrefix</code>,
+ <code>DownstreamCachePurgeMethod</code>, and
+ <code>DownstreamCacheRewrittenPercentageThreshold</code> support script
+ variables, so it's possible to set them on a per-request basis. Turn this on
+ with:
+<pre class="prettyprint">
+http {
+ pagespeed ProcessScriptVariables on;
+ ...
+}</pre>
+ You can then use script variables in arguments for these commands:
+<pre class="prettyprint">
+ pagespeed DownstreamCachePurgeLocationPrefix "$purge_location";
+ pagespeed DownstreamCachePurgeMethod "$cache_purge_method";
+ pagespeed DownstreamCacheRewrittenPercentageThreshold "$rewrite_threshold";</pre>
+</p>
+<p>
+ For more details on script variables, including how to handle dollar signs,
+ see <a href="system#nginx_script_variables">Script Variable Support</a>.
+</p>
+<h2 id="implementation">Implementation Details</h2>
+<p>
+ To support downstream caching PageSpeed sends a purge request to the caching
+ layer whenever it identifies an opportunity for more rewriting to be done on
+ content that was just served. Such opportunities could arise because of, say,
+ the resources now becoming available in the PageSpeed cache or an image
+ compression operation completing. The cache purge forces the next request for
+ the HTML file to come all the way to the backend PageSpeed server and obtain
+ better rewritten content, which is then stored in the cache. This interaction
+ between the PageSpeed server and the downstream caching layer is depicted in
+ the diagram given below.
+</p>
+ <img src="images/downstream_caching.png" >
+<p>
+ In the interaction depicted above, note that the partially optimized HTML will
+ be served from the cache until a purge request gets sent by the PageSpeed
+ server. It is recommended to set up PageSpeed and the downstream caching
+ layer servers on a one to one basis so that the purges can be sent to the
+ correct downstream server.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/experiment.html b/doc/experiment.html
new file mode 100644
index 0000000..af8933a
--- /dev/null
+++ b/doc/experiment.html
@@ -0,0 +1,449 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Experimenting with PageSpeed</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Experimenting with PageSpeed</h1>
+<h2 id="Framework">Experimental Framework</h2>
+<p>
+The <a href="module-run-experiment.html">Run Experiment</a> module allows you to
+gather data on what filters perform best for your site using A/B testing. It
+reports to your <a href="http://www.google.com/analytics/">Google Analytics</a>
+account, storing data in
+a <a href="/analytics/devguides/collection/gajs/gaTrackingCustomVariables">custom
+variable</a>. It often makes sense to first experiment manually using the
+per-request configuration described below to get an idea of which filters might
+help your site, and then <a href="module-run-experiment.html">run a controlled
+experiment</a> to test whether these filters actually speed it up in practice.
+</p>
+
+<h2 id="PerRequest">Per-request configuration</h2>
+
+<p>
+Query parameters, request headers, and response headers can be used to disable
+PageSpeed, specify the set of filters applied to an HTML page, and control some
+inlining limits.
+</p>
+
+<p>
+Query parameters take the form of <code>name=value</code>
+and parameters are separated by an ampersand (&). For example:
+</p>
+<pre>
+ <a href="http://modpagespeed.com/rewrite_css.html?PageSpeed=on&PageSpeedFilters=rewrite_css">http://modpagespeed.com/rewrite_css.html?PageSpeed=on&PageSpeedFilters=rewrite_css</a>
+</pre>
+
+<p>
+Request and response headers take the form of <code>name: value</code>
+and each header is on its own line. For example:
+</p>
+<pre class="prettyprint">
+GET /rewrite_css.html HTTP/1.1
+Host: modpagespeed.com
+PageSpeed: on
+PageSpeedFilters: rewrite_css</pre>
+
+<p>
+For backwards compatibility, these can start with <code>ModPagespeed</code>
+instead of <code>PageSpeed</code>, but this usage is deprecated.
+</p>
+
+<p>
+Query parameters can be added to the URL of the page or resource being
+fetched, request headers can be set in the request for pages and
+resources, and response headers can be set in the response of HTML
+pages (but not resources). These settings affect only the given
+request. If all three (query parameters and both headers) are used in
+the same request the query parameters will be applied first, followed
+by the request headers, followed by the response headers. Later
+settings override earlier settings but a filter disable in any
+location always overrides subsequent enables.
+</p>
+
+<p>
+There are two supported methods of adding response headers that PageSpeed will
+be able to observe and process. The first is to add response headers with a
+content handler such as PHP or Perl. The second is to add response headers at
+an origin server and run PageSpeed as a proxy in front of it. The use of
+mod_headers (Apache) or add_header (Nginx) on the same webserver as PageSpeed
+will not work because headers will be inserted after PageSpeed has already
+processed the page.
+</p>
+
+<h3 id="StickyQueryParams">Sticky Query Parameters</h3>
+<p>
+Query parameters can be set to be "sticky" and persist across
+requests using cookies. Sticky query parameters can be set by providing the
+sticky query parameter option in a request, and the server will respond with
+a cookie, valid for the duration specified in the PageSpeed configuration.
+</p>
+<p>
+To prevent abuse, a "secret token" must be provided in the initial
+request to enable setting cookies.
+</p>
+<dl>
+<dt>Apache:</dt>
+<dd>
+<pre class="prettyprint">ModPagespeedStickyQueryParameters example_token</pre>
+</dd>
+<dt>Nginx:</dt>
+<dd>
+<pre class="prettyprint">pagespeed StickyQueryParameters example_token</pre>
+</dd>
+</dl>
+<p>
+The duration, in milliseconds, for which the cookie will be valid can be set in
+the PageSpeed configuration.
+</p>
+<dl>
+<dt>Apache:</dt>
+<dd>
+<pre class="prettyprint">ModPagespeedOptionCookiesDurationMs 12345</pre>
+</dd>
+<dt>Nginx:</dt>
+<dd>
+<pre class="prettyprint">pagespeed OptionCookiesDurationMs 12345</pre>
+</dd>
+</dl>
+<p>
+The request must specify the token in a query parameter,
+for example:
+<pre>
+<a href="http://modpagespeed.com/rewrite_css.html?PageSpeedStickyQueryParameters=example_token&PageSpeedFilters=+remove_comments">http://modpagespeed.com/rewrite_css.html?PageSpeedStickyQueryParameters=example_token&PageSpeedFilters=+remove_comments</a></pre>
+<p>
+A request with the proper sticky query parameter token will cause the server to
+respond with a <code>Set-Cookie</code> in the response.
+Any request not containing the correct token will not receive the
+<code>Set-Cookie</code> response. Future responses with the received cookie will
+also enable the options set in the query parameter with the sticky query
+parameter. In this case, the <code>remove-comments</code> filter would be
+enabled.
+</p>
+
+<h3 id="ModPagespeed">Enabling and disabling PageSpeed</h3>
+
+<p>Query parameters:</p>
+<pre class="prettyprint">
+ PageSpeed=off
+ PageSpeed=on
+</pre>
+<p>Request & Response headers:</p>
+<pre class="prettyprint">
+ PageSpeed: off
+ PageSpeed: on
+</pre>
+<p>
+The first line disables PageSpeed rewriting, the second line enables it.
+</p>
+
+<h3 id="ModPagespeedFilters">Specifying the filters applied</h3>
+
+<p>Query parameters:</p>
+<pre class="prettyprint">
+ PageSpeedFilters=<i>comma-separated list of names</i>
+</pre>
+<p>Request & Response headers:</p>
+<pre class="prettyprint">
+ PageSpeedFilters: <i>comma-separated list of names</i>
+</pre>
+
+<p>
+This specifies the set of filters to apply to the page. The list of settings
+includes all filter names and a few shortcut names:
+</p>
+
+<ul>
+ <li><code>core</code> sets the rewrite level (per
+ <code><a href="config_filters.html#level>ModPagespeedRewriteLevel"
+ >RewriteLevel</a></code>)
+ to <code>CoreFilters</code>. This enables the core set of filters.</li>
+ <li><code>testing</code> enables all filters that are in the
+ <code>TestingCoreFilters</code> level but are not in the
+ <code>CoreFilters</code> level - this is not the same as setting the
+ level to <code>TestingCoreFilters</code> because that includes all
+ core filters, but the same effect can be achieved by specifying
+ both: <code>core,testing</code>.</li>
+ <li><code>rewrite_images</code> enables the following filters:
+ <code>inline_images</code>, <code>recompress_images</code>, and
+ <code>resize_images</code>.</li>
+ <li><code>extend_cache</code> enables the following filters:
+ <code>extend_cache_css</code>, <code>extend_cache_images</code>, and
+ <code>extend_cache_scripts</code>.</li>
+ <li><code>rewrite_javascript</code> enables the following filters:
+ <code>rewrite_javascript_external</code> and
+ <code>rewrite_javascript_inline</code>.</li>
+</ul>
+
+<p>
+When any filter is specified without a "<code>+</code>" or
+"<code>-</code>", any filters not explicitly enabled are
+disabled. Filters and shortcuts can be explicitly disabled by
+preceding the name by a minus sign ('-'), which is useful
+after using a shortcut. For example,
+"<code>core,-combine_css</code>" enables all the core
+filters
+<em>except</em> <code>combine_css</code>.
+</p>
+
+<p>
+If all names are prefixed with "<code>+</code>" or "<code>-</code>" then the
+filter set is incrementally adjusted from the current system settings based on
+the configuration files. For example, in a server
+with <code>RewriteLevel</code> set to <code>CoreFilters</code>, the query-string
+</p>
+<pre class="prettyprint">
+ ?PageSpeedFilters=+lazyload_images,-inline_images
+</pre>
+<p>
+will leave all the core filters enabled, but will add lazyload_images
+and disable inline images.
+</p>
+
+<h3 id="ModPagespeedFilters">Controlling inlining limits</h3>
+
+<p>Query parameters:</p>
+<pre class="prettyprint">
+ PageSpeedCssFlattenMaxBytes=<i>value</i>
+ PageSpeedCssImageInlineMaxBytes=<i>value</i>
+ PageSpeedCssInlineMaxBytes=<i>value</i>
+ PageSpeedImageInlineMaxBytes=<i>value</i>
+ PageSpeedJsInlineMaxBytes=<i>value</i>
+</pre>
+<p>Request & Response headers:</p>
+<pre class="prettyprint">
+ PageSpeedCssFlattenMaxBytes: <i>value</i>
+ PageSpeedCssImageInlineMaxBytes: <i>value</i>
+ PageSpeedCssInlineMaxBytes: <i>value</i>
+ PageSpeedImageInlineMaxBytes: <i>value</i>
+ PageSpeedJsInlineMaxBytes: <i>value</i>
+</pre>
+
+<p>
+These specify the limits for the following inlining options:
+</p>
+
+<ul>
+ <li><code>PageSpeedCssFlattenMaxBytes</code> sets the maximum size of CSS
+ files that will be flattened.</li>
+ <li><code>PageSpeedCssImageInlineMaxBytes</code> sets the maximum
+ size of images inside CSS. For inline CSS in HTML files, the
+ value used is the smaller of this value
+ or <code>PageSpeedImageInlineMaxBytes</code>.
+ <li><code>PageSpeedCssInlineMaxBytes</code> sets the maximum size of CSS
+ files that will be inlined.</li>
+ <li><code>PageSpeedImageInlineMaxBytes</code> sets the maximum size of
+ image files that will be inlined.</li>
+ <li><code>PageSpeedJsInlineMaxBytes</code> sets the maximum size of
+ JavaScript files that will be inlined.</li>
+</ul>
+
+<p>
+Here is an example that combines many of the above query parameters to enable
+all the core filters <em>except</em> the cache extension filters, and sets the
+JavaScript inlining limit to a high value so that most JavaScript files will
+be inlined:
+</p>
+<pre>
+ http://..../index.html?PageSpeedFilters=core,-extend_cache&PageSpeedJsInlineMaxBytes=102400
+</pre>
+
+<h3 id="Client-Options">Client options in queries and headers</h3>
+ <p>
+ This is an experimental option, its name and values are subject to change.
+ This option allows the client to customize the optimizations applied to a
+ request and can be used in a header or query parameter.
+ </p>
+
+ <p>As a query parameter:</p>
+<pre class="prettyprint">
+ X-PSA-Client-Options=<i>client-options</i>
+</pre>
+<p>As a Request or Response header:</p>
+<pre class="prettyprint">
+ X-PSA-Client-Options: <i>client-options</i>
+</pre>
+
+<p>
+The format of client-options is
+</p>
+<pre>
+ name1=value1,name2=value2, ...
+</pre>
+
+<p>
+The order of the name-value pairs does not matter. The supported options are:
+</p>
+
+<pre>
+ v=1
+</pre>
+<p>Version of the header. '1' is the only supported version for now.</p>
+<pre>
+ <code>m=integer-value</code>
+</pre>
+<p> Mode. Valid values are</p>
+ <ul>
+ <li> <code>0</code>, the client prefers that the server operates in its
+ default mode. </li>
+ <li> <code>1</code>, the client prefers that no image is transformed. </li>
+ <li> <code>2</code>, the client prefers that no resource is transformed.
+ This is equivalent to "?PageSpeedFilters=" in the request URL </li>
+ </ul>
+
+<pre>
+ <code>iqp=integer-value</code>
+</pre>
+<p> Image quality preference. Valid values are </p>
+ <ul>
+ <li> <code>0</code>, the client prefers that the server uses its own default
+ image quality. </li>
+ <li> <code>1</code>, the client prefers low image quality. </li>
+ <li> <code>2</code>, the client prefers medium image quality. </li>
+ <li> <code>3</code>, the client prefers high image quality. </li>
+ </ul>
+
+<h3 id="restrict-request-options">Restrict per-request configuration</h3>
+ <p class="note">
+ <strong>Note: New feature as of 1.9.32.1</strong>
+ </p>
+ <p>
+ Interpretation of PageSpeed query parameters and headers can be restricted to
+ requests specifying a request option override token.
+ The token is specified in the server configuration file and disallows
+ request option overriding when the request does not specify the correct token.
+ This option can be used to reduce the attack surface of denial of service
+ attacks.
+ </p>
+ <dl>
+ <dt>Apache:</dt>
+ <dd>
+ <pre class="prettyprint">ModPagespeedRequestOptionOverride example_token</pre>
+ </dd>
+ <dt>Nginx:</dt>
+ <dd>
+ <pre class="prettyprint">pagespeed RequestOptionOverride example_token</pre>
+ </dd>
+ </dl>
+ <p>
+ This feature provides a mechanism to restrict the ability for filters and
+ options to be specified in query parameters and request headers.
+ To enable it, an override token must be specified in the configuration file,
+ and requests must specify the same token for filters and options to be
+ applied.
+ Query parameters, except for <code>PageSpeed=on</code>,
+ <code>PageSpeed=off</code>, or <code>PageSpeed=noscript</code> will then only
+ be interpreted when accompanied by the correct
+ <code>RequestOptionOverride</code> token. For example, the rewrite_css filter
+ would be used in this example.
+ </p>
+ <p>
+ The request must specify the token in a query parameter or header,
+ for example:
+ <pre>
+ <a href="http://modpagespeed.com/rewrite_css.html?PageSpeed=on&PageSpeedFilters=rewrite_css&PageSpeedRequestOptionOverride=example_token">http://modpagespeed.com/rewrite_css.html?PageSpeed=on&PageSpeedFilters=rewrite_css&PageSpeedRequestOptionOverride=example_token</a></pre>
+ <p>
+ Any request not containing the correct <code>RequestOptionOverride</code>
+ token or not containing a <code>RequestOptionOverride</code> token will ignore
+ all other PageSpeed filters and options specified.
+ </p>
+ <p class="note">
+ <strong>
+ Note: even if applied, PageSpeed=on/off/noscript still takes effect.
+ </strong>
+ </p>
+</h3>
+
+<h3 id="noop">Noop query-parameter</h3>
+<p class="note">
+ <strong>Note: New feature as of 1.10.33.0</strong>
+</p>
+<p>
+To help bust browser caches, especially with experiments, any
+PageSpeed URL can accept the
+<code>PageSpeedNoop</code> query-paramter with an integer value. This
+query-parameter will be ignored by PageSpeed and stripped from the
+URL early in the processing flow. The origin will not see the <code>Noop</code>
+parameter, and PageSpeed's server-caches will not be affected. However, it
+will prevent your browser from using a cached value.
+</p>
+
+<p>Examples:</p>
+<pre class="prettyprint"
+ >http://images.example.com/foo.png?PageSpeedNoop=571
+http://www.example.com/index.html?q=foo&PageSpeedNoop=99438
+</pre>
+
+<h2 id="Configuring-mod_pagespeed_examples">
+ Configuring mod_pagespeed_examples</h2>
+<p class="note"><strong>Note: Apache-only</strong></p>
+
+<p>
+mod_pagespeed ships with a directory of sample HTML, JavaScript,
+Image, and CSS files to demonstrate the rewrite passes that it
+executes. These also form the basis of an installation smoke-test to
+ensure that the configured system is operating correctly. Assuming
+the files are installed in /var/www/mod_pagespeed_example, the
+following configuration file fragment will enable them to be served
+using reasonable caching headers.
+</p>
+<pre class="prettyprint lang-sh">
+ # These caching headers are set up for the mod_pagespeed example, and
+ # also serve as a demonstration of good values to set for the entire
+ # site, if it is to be optimized by mod_pagespeed.
+
+ <Directory /var/www/mod_pagespeed_example>
+ # To enable to show that mod_pagespeed to rewrites web pages, we must
+ # turn off Etags for HTML files and eliminate caching altogether.
+ # mod_pagespeed should rewrite HTML files each time they are served.
+ # The first time mod_pagespeed sees an HTML file, it may not optimize
+ # it fully. It will optimize better after the second view. Caching
+ # defeats this behavior.
+ <FilesMatch "\.(html|htm)$">
+ Header unset Etag
+ Header set Cache-control "max-age=0, no-cache"
+ </FilesMatch>
+
+ # Images, styles, and JavaScript are all cache-extended for
+ # a year by rewriting URLs to include a content hash.. mod_pagespeed,
+ # can only do this if the resources are cacheable in the first place.
+ # The origin caching policy, set here to 10 minutes, dictates how
+ # frequently mod_pagespeed must re-read the content files and recompute
+ # the content-hash. As long as the content doesn't actually change,
+ # the content-hash will remain the same, and the resources stored
+ # in browser caches will stay relevant.
+ <FilesMatch "\.(jpg|jpeg|gif|png|js|css)$">
+ Header unset Etag
+ Header set Cache-control "public, max-age=600"
+ </FilesMatch>
+ </Directory>
+</pre>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/faq.html b/doc/faq.html
new file mode 100644
index 0000000..fae2ab5
--- /dev/null
+++ b/doc/faq.html
@@ -0,0 +1,777 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Frequently Asked Questions</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Frequently Asked Questions</h1>
+<h2 id="other-servers">I'm not running Apache or Nginx, do you support my
+http server?</h2>
+
+<p>
+While we only support Apache and Nginx, there are community developed ports to
+several other webservers:
+</p>
+<ul>
+<li><a
+href="https://cwiki.apache.org/confluence/display/TS/ats_speed">Apache
+Traffic Server</a></li>
+<li><a href="http://www.iispeed.com/"
+>Internet Information Services (IIS)</a></li>
+<li><a
+href="http://open.litespeedtech.com/mediawiki/index.php/Help:Modules:PageSpeed"
+>OpenLiteSpeed</a></li>
+</ul>
+<p>
+If you run a webserver that doesn't have a port, one option would be to set up
+some other server running PageSpeed as a reverse proxy in front of it. If
+you're not sure which to use we recommend using PageSpeed on nginx, but any of
+these servers should work well as an optimizing reverse proxy.
+</p>
+<p>
+(And, of course, if you're interested in porting PageSpeed to a new server, that
+would be awesome, and anyone porting should feel free to send us lots of
+detailed technical questions!)
+</p>
+
+<h2 id="when-support">When will you support my favorite OS or protocol?</h2>
+
+<p>
+While we have no dates to announce for upcoming releases, we definitely want to
+know what you think we should be working
+on. Please <a href="https://github.com/apache/incubator-pagespeed-mod/issues">search
+our issues</a> for your feature. If you don't find
+it, <a href="https://github.com/apache/incubator-pagespeed-mod/issues/new">open a new
+issue</a> and tag it "Type-Enhancement". To get updates on an issue, click the
+"star" icon for it. This also lets us know how many people are interested in
+the issue. If your issue is Nginx-specific, consider posting on
+the <a href="https://github.com/apache/incubator-pagespeed-ngx/issues">ngx_pagespeed
+bug tracker</a>.
+</p>
+
+<h2 id="suse">Do you support SUSE?</h2>
+<p>
+We support SUSE on Apache and Nginx when <a href="build_from_source">building
+from source</a>. For Apache, Robert Munteanu (robert.munteanu@gmail.com) has
+set up a repository which publishes OpenSUSE RPMs for mod_pagespeed. The
+repository is
+hosted <a href="http://software.opensuse.org/package/apache2-mod_pagespeed">on
+OpenSUSE's build service instance</a>. The builds have seen some testing on one
+of Robert's servers (OpenSUSE 12.1/x86_64) but he'd appreciate anyone else
+testing it.
+</p>
+<p>
+To enable the module, install it, add <code>deflate pagespeed</code> to your
+list of Apache modules in <code>/etc/sysconfig/apache2</code> and restart
+Apache.
+</p>
+<p>
+Please note that the module is linked dynamically with the current system
+libraries and as such will bring in more dependencies than the 'stock' Fedora or
+CentOS RPM.
+</p>
+
+<h2 id="not-rewriting">Why isn't PageSpeed rewriting any of my pages?</h2>
+<p>
+Check the HTTP response headers from your HTML page:
+</p>
+<pre class="prettyprint lang-bsh">
+ curl -D- http://example.com | less
+</pre>
+<p>
+You should get something like:
+</p>
+<dl>
+ <dt>Apache:<dd>
+<pre>
+Date: Fri, 30 Sep 2016 15:36:57 GMT
+Server: Apache/2.4.7 (Ubuntu)
+...
+X-Mod-Pagespeed: 1.11.33.4-0
+...
+</pre>
+ <dt>Nginx:<dd>
+<pre>
+Date: Fri, 30 Sep 2016 15:37:24 GMT
+Server: nginx/1.11.4
+...
+X-Page-Speed: 1.11.33.4-0
+</pre>
+</dl>
+<p>
+If you don't see an <code>X-Mod-Pagespeed</code> header (Apache)
+or <code>X-Page-Speed</code> header (Nginx), this means that your webserver
+isn't letting PageSpeed run. This could be because it isn't actually installed,
+you don't have it turned on in the configuration file, or many other reasons.
+In Apache the problem might be that you have multiple
+<code>SetOutputFilter</code> directives: only one of those will win. See the
+Apache <a
+href="http://httpd.apache.org/docs/current/mod/core.html#SetOutputFilter"
+>SetOutputFilter documentation</a>.
+</p>
+<p>
+If you do see the header, but it doesn't look like PageSpeed is making any
+changes to your page, its possible that none of the active filters are finding
+anything to rewrite. Try comparing your page with PageSpeed off and with
+the <a href="filter-whitespace-collapse">collapse_whitespace</a> filter enabled:
+</p>
+<pre class="prettyprint">
+ curl -D- 'http://example.com?ModPagespeed=off' | less
+ curl -D- 'http://example.com?ModPagespeed=on&ModPagespeedFilters=collapse_whitespace' | less
+</pre>
+<p>
+If you see a change when run with <code>collapse_whitespace</code> on, that
+means PageSpeed is running but the filters you have selected aren't
+optimizing anything. There are several reasons that could happen:
+</p>
+<ul>
+ <li>The filters you have enabled aren't aggressive enough.</li>
+ <li>Your resources (images, css, javascript) aren't cacheable. If
+ PageSpeed sees <code>cache-control</code> headers such
+ as <code>nocache</code> or <code>private</code> it will not rewrite the
+ resources.</li>
+ <li>CSS, JavaScript, and image files served from a distinct domain from the
+ HTML must have the resource domain authorized. See
+ <a href="domains">Domains</a>.</li>
+ <li>Your CSS has new CSS3 syntax or other constructions we don't support.
+ See <a href="http://github.com/apache/incubator-pagespeed-mod/issues/108"
+ >issue 108</a>.
+ The <a href="filter-css-rewrite#configuration"
+ >fallback_rewrite_css_urls</a> filter may be able to help. You can also
+ use the <a href="build_from_source#debug-css">standalone CSS parser</a> to
+ help debug these issues.</li>
+ <li>Your resources are served over HTTPS. HTTPS resources can currently only
+ be rewritten if they are origin-mapped or loaded from directly from the
+ file-system. See <a href="https_support">HTTPS Support</a>.</li>
+</ul>
+
+<h2 id="missing-dependency">Why am I getting "Error: Missing Dependency: httpd > = 2.2" even though I have Apache 2.2.? installed?</h2>
+<p>
+ You are probably trying to install mod_pagespeed using yum or apt-get
+ (the .rpm or .deb binaries), but you installed Apache using a different
+ method (cPanel, Wordpress, etc.). This will not work because mod_pagespeed
+ binaries depend upon Apache being installed using yum or apt-get.
+</p>
+<p>
+ Instead you must either
+ <a href="build_mod_pagespeed_from_source">
+ build from mod_pagespeed from source
+ </a>
+ or <a href="http://www.google.com/">search</a> for mod_pagespeed + your
+ platform to see if someone has documented an install process for that
+ platform. For example,
+ <a href="#cpanel-install">cPanel based installation</a>.
+</p>
+
+<h2 id="cpanel-install">I'm using cPanel on my server, how do I install mod_pagespeed?</h2>
+<p>
+cPanel installs Apache httpd server from source via the built-in EasyApache setup
+and build process. In order to enable mod_pagespeed on your server, download
+and install the <a href="https://github.com/apache/incubator-pagespeed-cpanel">mod_pagespeed module
+ for cPanel WHM</a> - once the module is installed, you can select "mod_pagespeed" as
+one of the modules during the regular EasyApache build (via the online tool, or from
+the command line). Do not install mod_pagespeed from .deb. or .rpm packages - cPanel
+requires that you use the EasyApache build process.
+</p>
+
+<h2 id="wordpress-blank">I'm using WordPress and my pages are blank. Why?</h2>
+<p>
+Disable compression in the WordPress plugin, so that mod_pagespeed will process
+uncompressed HTML. mod_pagespeed ensures that its output will be compressed by
+enabling <a href="http://httpd.apache.org/docs/current/mod/mod_deflate.html"
+>mod_deflate</a>.
+</p>
+
+<h2 id="broken">PageSpeed broke my site; what do I do?</h2>
+<p>
+First of all, sorry about that. We put a lot of work into validating our
+rewriters against a large corpus of websites and we disable filters that cause
+problems as soon as we can, but sometimes things slip through.
+</p>
+<p>
+Second, please upgrade to the latest version; we are continually working on
+bug-fixes and turning off filters that break pages.
+</p>
+If it's still breaking your site, please post a bug
+(<a href="https://github.com/apache/incubator-pagespeed-mod/issues/new">Apache</a>,
+ <a href="https://github.com/apache/incubator-pagespeed-ngx/issues/new">Nginx</a>). If
+you can, including the following information will make it much easier to
+diagnose:
+<ol>
+ <li>Try appending <code>?ModPagespeed=off</code> to the URL. This de-activates
+ PageSpeed. If the site is still broken, it is not a rewrite
+ or HTML parsing problem. It might be a configuration clash, please ask us
+ on our <a href="mailing-lists#discussion">discussion group</a>.</li>
+ <li>If that fixed the site, try
+ appending <code>?ModPagespeed=on&ModPagespeedFilters=</code> to the
+ URL. This turns on PageSpeed, but no filters. If the site is broken
+ now, it is an HTML parsing
+ problem. Please <a href="mailing-lists#discussion">let us know</a>.</li>
+ <li>If the site still worked, try
+ appending <code>?ModPagespeed=on&ModPagespeedFilters=foo</code> for
+ various filters "foo". For example try:
+ <pre class="prettyprint lang-bsh">
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=extend_cache
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=combine_css
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=inline_css
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=inline_javascript
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=insert_image_dimensions
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=rewrite_images
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=rewrite_css
+http://www.modpagespeed.com/?ModPagespeed=on&ModPagespeedFilters=rewrite_javascript</pre>
+ You may have to reload them a few times over several seconds to make sure
+ they have had time to load sub-resources into cache and rewrite them. If
+ one of these breaks your site, you now know which filter is at
+ fault. Please <a href="mailing-lists#discussion">let us know</a>. You can
+ disable that filter by adding a line to your <code>pagespeed.conf</code>
+ file:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisableFilters foo</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed DisableFilters foo;</pre>
+</dl>
+ </li>
+</ol>
+
+<h2 id="mod_rewrite">I am getting 404s for rewritten resources
+ (like example.png.pagespeed.ic.LxXAhtOwRv.png) or for the
+ mod_pagespeed_admin console</h2>
+<p>
+ The most common reason that the rewritten resources 404 is because of
+ mod_rewrite <code>RewriteCond</code> rules. For example:
+</p>
+<pre class="prettyprint">
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^ /404 [L,R=301]</pre>
+<p>
+ This rule causes 404 for all requests which don't exist on the filesystem,
+ including mod_pagespeed rewritten resources and the mod_pagespeed admin
+ console.
+</p>
+<p>
+ In order to fix this you must add an exception for mod_pagespeed URLs:
+</p>
+<pre class="prettyprint">
+ RewriteCond %{REQUEST_URI} !pagespeed</pre>
+<p>
+ This will allow rewritten resources, the admin console and static resources
+ necessary for some filters.
+</p>
+
+<h2 id="ignores-changes">PageSpeed does not pick up changes when I edit CSS
+or JavaScript files</h2>
+<p>
+There are two distinct cache-times at play when you use PageSpeed:
+<ol>
+ <li>The origin TTL which PageSpeed uses to refresh its internal
+ server-side cache.</li>
+ <li>The TTL with which PageSpeed serves rewritten resources to
+ browsers.</li>
+</ol>
+When PageSpeed first reads your resource file, it uses the origin TTL to figure
+out how often to re-examine the origin CSS file. Assume your origin TTL is 1
+day. Once PageSpeed has that file in cache, it will not go back & re-check
+that file for a day. Changing the TTL after PageSpeed has put the resource in
+its cache will not help because PageSpeed is not going to reload the resource
+until the one in its cache expires, or you <a href="system#flush_cache">clear
+its cache</a>.
+</p>
+<p>
+We recommend an origin TTL of 10 minutes, which provides reasonable
+responsiveness when you update a file. If you try to make it much smaller, then
+your server will need to refresh it more frequently. This adds server load and
+reduces optimization.
+</p>
+<p>
+To see changes to your files more quickly while
+developing, <a href="system#flush_cache">flush the cache</a> on your server(s).
+</p>
+<p>
+If your environment allows you to
+enable <a href="domains#ModPagespeedLoadFromFile">LoadFromFile</a>,
+you can get the best of both worlds because PageSpeed can eliminate its
+internal server-side cache.
+</p>
+<h2 id="tiny-mce-errors">Why is PageSpeed giving me errors in jquery or
+js_tinyMCE?</h2>
+<p>
+Some JavaScript is introspective, being sensitive to its own name or the path
+it's loaded from. While PageSpeed has an internal list
+(<a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/net/instaweb/rewriter/rewrite_options.cc">DisallowTroublesomeResources</a>)
+hardcoded with filenames of JavaScript libraries that are known to be
+problematic, and <a href="restricting_urls#aris">inspects the source of
+others</a> looking for dangerous constructs, it doesn't always correctly
+determine whether it is safe to rewrite a given file. If you have a file that
+is giving JavaScript errors, you can tell PageSpeed to leave it alone with
+<a href="restricting_urls">Disallow</a>.
+</p>
+<h2 id="name-resolution-failure">What's with all these "Serf" errors in my logs?
+Error status=670003 (Temporary failure in name resolution)</h2>
+<p>
+This can happen when the DNS cannot be accessed accurately from the server. Thus
+sub-resources cannot be fetched and rewritten correctly.
+</p>
+<p>
+To test that this is the case, <code>ssh</code> into your machine and <code>wget</code> a URL:
+</p>
+<pre class="prettyprint lang-bsh">
+ $ ssh YOUR_SITE
+ $ wget http://YOUR_SITE/
+</pre>
+<p>
+If this fails, then DNS is not accessible or there is some other networking
+issue stopping you from accessing your host from itself.
+</p>
+<p>
+One solution is to use <a href="domains#mapping_origin">origin-mapping</a> to
+indicate the host from which the resources should be fetched:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMapOriginDomain localhost www.example.com</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MapOriginDomain localhost www.example.com;</pre>
+</dl>
+<p>
+This bypasses DNS lookup by telling PageSpeed to get all resources for
+domain <code>www.example.com</code> from <code>localhost</code>.
+</p>
+<p>
+This can also be used to improve the performance of PageSpeed when it is
+sitting behind a load balancer. It may be preferable to use localhost to load
+the resources rather than going out to the load-balancer and back.
+</p>
+<h2 id="tmpfs">Can I move PageSpeed's file-based cache into RAM?</h2>
+<p>
+Why yes, you can. PageSpeed uses the file system for its cache
+implementation. There is no requirement that this be a physical disk. Disk
+pressure will be reduced and performance may be improved by using a memory-based
+file system.
+</p>
+<p>
+Put this in <code>/etc/fstab</code>, with the uid and guid set to the appropiate
+user and group of your webserver, and set path to your needs. Feel free to
+change the size; here it is 256Mb:
+<pre class="prettyprint lang-bsh">
+ tmpfs /path/to/pagespeed_cache tmpfs size=256m,mode=0775,uid=httpd,gid=httpd 0 0
+</pre>
+<p>
+Save it, and after that mount the tmpfs:
+</p>
+<pre class="prettyprint lang-bsh">
+ mount /path/to/pagespeed_cache
+</pre>
+<h2 id="configure-make">Why don't you allow source-installs in Apache via
+./configure && make?</h2>
+<p>
+mod_pagespeed is dependent on several other packages that
+use <code>gclient</code>. For us to switch away from this build methodology
+we'd have to either:
+</p>
+<ul>
+ <li>rewrite the functionality we get for free from other packages,
+ <b>or</b></li>
+ <li>get these packages to switch
+ methodologies <b>and</b> document for people installing from source that
+ they must <code>configure</code> and <code>make</code> about 10 other
+ packages before they could compile ours.</li>
+</ul>
+<p>
+To do either of those would cost us a lot of development time that we'd prefer
+to spend making PageSpeed better. The benefit of <code>gclient</code>,
+besides the above, is that it lets us control explicitly which library versions
+we link in, out of a large number of direct and transitive dependencies, helping
+us create a consistent experience for our source-code builds. If we had to ask
+our source-code installers to <code>configure</code> and <code>make</code>
+multiple dependent libraries there would likely be a lot of
+version-incompatibilities.
+</p>
+<p>
+We do support <code>./configure && make</code> in Nginx, but that only works
+because we package up a binary distribution of the PageSpeed Optimization
+Library and a "<a href="build_ngx_pagespeed_from_source">source</a>"
+installation only builds the ngx_pagespeed-specific files from source. When you
+want
+to <a href="https://github.com/apache/incubator-pagespeed-ngx/wiki/Building-PSOL-From-Source">build
+PSOL from source along with ngx_pagespeed</a> you still need to
+use <code>gclient</code>.
+</p>
+<h2 id="tracking-image">Why is my Google Analytics data being inflated by
+"Serf"?</h2>
+<p>
+If you track page views with a tracking image, you will need to explicitly tell
+PageSpeed not to try to fetch that image. For example if your tracking image
+were:
+</p>
+<pre class="prettyprint">
+ <img src="/ga.php?utmac=...">
+</pre>
+<p>
+you would add:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisallow "*/ga.php*"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed Disallow "*/ga.php*";</pre>
+</dl>
+<p>
+to your configuration file.
+</p>
+<h2 id="mod_php">mod_pagespeed does not rewrite pages produced from mod_php</h2>
+<p>
+mod_pagespeed only rewrites pages specifically marked as <code>Content-Type:
+text/html</code> (and a few other HTML types). If you dynamically generate your
+pages from mod_php, PHP needs to set this header correctly.
+</p>
+<p>
+One way to do this is to use the PHP's <a href="http://php.net/manual/en/function.header.php">header function</a>:
+</p>
+<pre class="prettyprint">
+ <?php
+ header('Content-Type: text/html')
+ ?>
+</pre>
+<p>
+This code goes at the top of your php file.
+</p>
+<h2 id="meta_tags_and_xhtml">PageSpeed causes my page to display an <code>XML
+Parsing Error</code> message</h2>
+<p>
+This usually happens when using a content management or generation system
+(we've seen it with Munin and Magento for example). The full error message
+looks something like:
+</p>
+<pre class="prettyprint">
+ XML Parsing Error: mismatched tag. Expected: </li>.
+ Location: http://www.example.com/
+ Line Number 123, Column 4: </ul>
+</pre>
+<p>
+This happens when the generated content has a <code>meta</code> tag that
+identifies the content as XHTML but the content has markup that is not valid
+XHTML, <em>and</em> you have configured your webserver to set the content type
+to HTML, so the browser parses it as HTML and doesn't detect the invalid XHTML
+errors.
+</p>
+<p>
+However, when <code>convert_meta_tags</code> is enabled (and it's a core filter
+so is on by default), PageSpeed inserts a content header into the response
+with the value in the <code>meta</code> tag, namely XHTML
+(<code>application/xhtml+xml</code> to be precise), resulting in the browser
+displaying the error message because it is now parsing the page as XHTML and
+it rejects the invalid content.
+</p>
+<p>
+There are three solutions, in descending order of preference:
+<ul>
+<li>If the content is XHTML, write XHTML and validate it with an XHTML
+ validator.</li>
+<li>If the content is not XHTML, remove the <code>meta</code> tag that claims
+ it is.</li>
+<li>If the content is not XHTML but you can't remove the <code>meta</code> tag,
+ say because your CMS doesn't let you, disable the
+ <code>convert_meta_tags</code> filter in your <code>pagespeed.conf</code>:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedDisableFilters convert_meta_tags</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed DisableFilters convert_meta_tags;</pre>
+</dl>
+</li>
+</ul>
+<h2 id="selinux_permissions">Why do I get <em>Permission denied</em> errors
+ in my log file on CentOS, RHEL, or any system using SELinux?</h2>
+<p>
+The symptom is many error messages in the webserver log file of the form (split
+across multiple lines here for readability):
+</p>
+<pre class="prettyprint">
+ [Mon Jan 01 02:03:04 2001] [error] [mod_pagespeed 1.0.22.7-2005 @1234]
+ /path/to/pagespeed_cache/randomgibberish.lock:0:
+ creating dir (code=13 Permission denied)
+</pre>
+<p>
+These are because SELinux by default restricts permissions of daemons for
+extra security, so you need to grant permission for the <code>httpd</code>
+or daemon to write to the cache directory:
+</p>
+<pre class="prettyprint">
+ chcon -R -t httpd_sys_content_t /path/to/pagespeed_cache
+</pre>
+This is for Apache; we're not sure what you need to do for Nginx.
+
+<h2 id="loopback_fetches">My logs contain messages about missing
+files requested from 224.0.0.0 and resources are not optimized, what's wrong?</h2>
+<p>
+
+For <a href="CVE-2012-4001">security reasons</a>, PageSpeed will only fetch
+from host names it is explicitly told about via its domain configuration
+directives and from 127.0.0.1, the loopback interface of the server it's running
+on. Many Apache configuration management tools, however, will configure virtual
+hosts to only listen on the external IP, which causes those fetches to fail.
+<p>
+If you are affected, the following options may be appropriate:
+<ul>
+ <li>Unless you have a reason not to, have your virtual hosts listen on all
+ interfaces: change the directives of the form
+ <code><VirtualHost 198.51.100.1:80></code> to the form
+ <code><VirtualHost *:80></code>
+ </li>
+ <li>For every virtual host, list its domain name(s) with the
+ <code>ModPagespeedDomain</code> directive inside its own
+ <code><VirtualHost></code> block. For example:
+ <pre class="prettyprint">
+<VirtualHost 198.51.100.1:80>
+ServerName www.example.com
+ModPagespeedDomain www.example.com
+</pre>
+ </li>
+ <li>For every virtual host, provide a <a href="domains#mapping_origin">
+ <code>ModPagespeedMapOriginDomain</code></a> directive giving where to load
+ its resources, for example:
+ <pre class="prettyprint">
+<VirtualHost 198.51.100.1:80>
+ServerName www.example.com
+ModPagespeedMapOriginDomain 198.51.100.1 www.example.com
+</pre>
+ </li>
+ <li>If you have <a href="configuration#virtual-hosts">
+ <code>ModPagespeedInheritVHostConfig on</code></a>, you can also provide the
+ origin mapping globally, which may be useful in combination with wildcards,
+ for example:
+ <pre class="prettyprint">
+ModPagespeedMapOriginDomain loadbalancer.example.com *.example.com
+</pre>
+
+ <p class="warning"><b>Warning:</b> You do not generally want to use
+ <code>Domain</code> globally as doing so will tell PageSpeed
+ that you consider all of these domains as mutually trusting.</p>
+ </li>
+ <li>If you are running a proxy or for some other reason cannot easily
+ enumerate all virtual hosts, it is possible to disable this behavior,
+ after taking some precautions. Please see
+ <a href="domains#fetch_servers">fetch server restrictions</a> for
+ more information.
+ </li>
+</ul>
+
+<h2 id="beacons">Why are rewritten pages sending POSTs back to my server?</h2>
+<p>
+Certain filters need to determine things about the page: in particular, the
+<code><a href="filter-lazyload-images">lazyload_images</a></code>,
+<code><a href="filter-inline-preview-images">inline_preview_images</a></code>,
+and <code><a href="reference-image-optimize#inline_images">inline_images</a>
+</code> filters need to determine which images are above the fold, and the
+<code><a href="filter-prioritize-critical-css">prioritize_critical_css</a>
+</code>filter needs to determine the CSS actually used by the page.
+<p>
+</p>To do this, the filters inject JavaScript into the rewritten HTML that
+analyzes the page in the browser and sends data back to mod_pagespeed using a
+POST method. The default target is <code>/mod_pagespeed_beacon</code> but that
+can be changed using the <code>
+<a href="filter-instrumentation-add#beacon_url">ModPagespeedBeaconUrl</a>
+</code> directive.
+</p>
+
+<h2 id="control_beacons">How do I enable or disable beacon POSTs being sent back
+to my server?</h2>
+<p>
+Filters that use the beacon automatically inject JavaScript to send the POST
+back to the server, and the POST handler is always enabled in mod_pagespeed,
+so there's nothing to do to enable beaconing.
+</p>
+<p>
+To disable the use of beacons by the image rewriting filters use the <code>
+<a href="config_filters#beacons">ModPagespeedCriticalImagesBeaconEnabled</a>
+</code> directive. If you disable image beacons but enable filters that use
+them, the filters will work but not as well as when beacons are enabled.
+<p>
+To disable the POST handler for all filters there are two options: either
+disable all the filters that use it, or use a
+<code><Location></code> directive to block it. Filters are disabled using
+<a href="config_filters#enabling">ModPagespeedDisableFilters</a>. An example
+<code><Location></code> directive to block all beacon POST handling that
+can be added to your <code>pagespeed.conf</code> file is:
+<pre class="prettyprint" id="disable_handler">
+ <Location /mod_pagespeed_beacon>
+ Order allow,deny
+ </Location>
+</pre>
+<p>
+If you block POSTs but enable filters that use beacons, depending on the filter
+it will either have limited functionality or have no useful effect, but in all
+cases pointless processing will occur in both the server and the browser, so
+you should disable and forbid these filters if you block POSTs.
+</p>
+<p class="note">
+<strong>Note:</strong>Even if you disable all filters that use beacons someone
+could use tools like <code>wget</code> or <code>curl</code> to send POSTs to
+your server. These will have no effect but they will require processing. If you
+want to completely disable POST handling use a <code><Location></code>
+directive.
+</p>
+
+<h2 id="noscript-redirect">Why is PageSpeed inserting a meta refresh to
+/?PageSpeed=noscript or /?ModPagespeed=noscript at the top of the page?</h2>
+<p>
+The <code><a href="filter-js-defer">defer_javascript</a></code>,
+<code><a href="filter-lazyload-images">lazyload_images</a></code>,
+<code><a href="filter-dedup-inlined-images">dedup_inlined_images</a></code>, and
+<code><a href="filter-local-storage-cache">local_storage_cache</a></code>
+filters require JavaScript to render pages correctly. To support clients that
+have JavaScript disabled, if any of these filters are enabled, PageSpeed will
+insert a meta refresh inside a <code>noscript</code> tag at the top of the page.
+This meta refresh will redirect clients with JavaScript disabled to the current
+URL with a '<code>?PageSpeed=noscript</code>' query parameter appended which
+disables filters that require JavaScript.
+</p>
+<p>
+If you wish to disable this redirect, for instance if your page already requires
+JS to function correctly, set the following option in your
+<code>pagespeed.conf</code>:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedSupportNoScriptEnabled false</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed SupportNoScriptEnabled false;</pre>
+</dl>
+</p>
+
+
+<h2 id="collapse-newlines">Why won't the <code>collapse_whitespace</code> filter
+remove newlines?</h2>
+
+<p>
+When removing whitespace from HTML, some website optimizers remove newlines
+entirely, but PageSpeed leaves them in. This isn't actually a problem with newlines,
+however, it's that it's not generally safe to remove a run of whitespace
+entirely. You can turn any number of consecutive whitespace characters into a
+single one, and we do that, but removing the whole run can make the site render
+differently.
+</p>
+
+<p>
+To take a simple example, consider:
+</p>
+
+<pre>
+ <body>
+ <h1>Hello World</h1>
+ Lorem ipsum dolor sit amet, consectetur
+ adipiscing elit. Fusce molestie ante <b>vitae</b>
+ iaculis varius. ...
+ </body>
+</pre>
+
+<p>
+PageSpeed with <code>collapse_whitespace</code> will turn this into:
+</p>
+
+<pre>
+<body>
+<h1>Hello World</h1>
+Lorem ipsum dolor sit amet, consectetur
+adipiscing elit. Fusce molestie ante <b>vitae</b>
+iaculis varius. ...
+</body>
+</pre>
+
+<p>
+If PageSpeed went further and put it all on one line, it would be
+converting <code><b>vitae</b> iaculis</code>
+into <code><b>vitae</b>iaculis</code>, which would change the
+rendering from "<b>vitae</b> iaculis" into "<b>vitae</b>iaculis"; one word
+instead of two. It would have been safe to turn <code><body>
+<h1>Hello World</h1></code> into <code><body><h1>Hello
+World</h1></code>, but doing one and not the other requires understanding
+the CSS (and JS) to the point where we can reliably tell that one pair of
+elements are <code>display: block</code> while the other pair
+are <code>display: inline</code>.
+</p>
+
+<h2 id="warning-fetch-rate">I've got a warning saying
+"Serf fetch failure rate extremely high". What does this mean?</h2>
+
+<p>The warning means that, when PageSpeed tried to fetch resources inside your
+web page for optimization, over 50% of attempts inside a 30-minute period
+failed. This may just mean you have some broken resource includes in your
+pages (in which case, it may be a good idea to fix them for better performance),
+but might indicate that PageSpeed's fetching is not working properly. If you
+have in-place resource optimization on, that can result in user requests for
+<code>.pagespeed.</code> URLs returning error 404 intermittently.</p>
+
+<p>First of all, check to see if the log mentions anything else about fetch
+trouble. If what's there is not helpful, the root cause may be more obvious
+if you follow these steps:</p>
+<ol>
+<li>Disable <a href="system#ipro">in-place resource optimization</a> temporarily.
+ </li>
+<li>Clear PageSpeed cache.</li>
+<li>Open a test page with a <code>?PagespeedFilters=+debug</code> query
+ parameter, reload it a few times, and see if resources are getting optimized,
+ and if not if there is an error message.
+<li>Revert the config changes.</li>
+</ol>
+
+<p>Most likely you may need to configure an <a href="domains#mapping_origin">
+origin domain, to specify the host or IP to talk to fetch resources.</p>
+
+<p>You may also want to consider using <a href="domains#ModPagespeedLoadFromFile">
+<code>LoadFromFile</code></a> functionality, as that performs much better if
+your resources are static.</p>
+
+<h2 id="varying-results">Sometimes pages are served as partially optimized. How can
+I achieve a more steady optimization ouput?</h2>
+
+<p>There are two (relatively) common situations that may lead up to a fluctuating
+level of optimization in the output:
+<ol>
+<li>Low traffic, combined with short http expiry times for image, css and javascript
+responses: <br/>
+Consider increasing the http expiry applied to the original
+resources, or set up <a href="domains#ModPagespeedLoadFromFile">LoadFromFile</a>
+to allow the module to load static files directly from disk.</li>
+<li>High cache churn rates:<br/>
+If PageSpeed's caches are sized too small, optimized assets falling out of the cache
+may cause frequent reoptimization. <a href="system#caching">Sizing the cache</a> to 3
+to 4 times the size of the original assets of the website should allow the module to
+cache all the original resources plus multiple optimized variants (for serving
+different user-agents and screen sizes).
+</li>
+<li>If the above did not help, the <a href="admin">admin pages</a> offer various tools
+that may assist in diagnosing what happens.</li>
+</ol>
+
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-attribute-elide.html b/doc/filter-attribute-elide.html
new file mode 100644
index 0000000..dc8ede5
--- /dev/null
+++ b/doc/filter-attribute-elide.html
@@ -0,0 +1,119 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Elide Attributes</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Elide Attributes</h1>
+
+
+<h2>Configuration</h2>
+<p>
+The 'Elide Attributes' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters elide_attributes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters elide_attributes;</pre>
+</dl>
+<p>
+in the configuration file.
+
+<h2>Description</h2>
+<p>
+The 'Elide Attributes' filter reduces the transfer size of HTML files
+by removing attributes from tags when the specified value is equal to
+the default value for that attribute. This can save a modest number of
+bytes, and may make the document more compressible by canonicalizing
+the affected tags.
+</p>
+
+<h2>Operation</h2>
+<p>
+There are two cases where an attribute value can be removed. First,
+some attributes are "single-valued" or "boolean", in that the value
+specified for the attribute is irrelevant -- all that matters is
+whether the attribute is present or not. In such cases, the filter
+will remove the value from the tag, leaving only the attribute name.
+</p>
+<p>
+For example, the following tag:
+</p>
+<pre class="prettyprint">
+ <button name="ok" disabled="disabled">
+</pre>
+<p>
+can be rewritten to:
+</p>
+<pre class="prettyprint">
+ <button name="ok" disabled>
+</pre>
+<p>
+The second case is an optional attribute with a default value. If an
+HTML attribute includes an explicit value for an attribute (perhaps to
+aid readability) that is equal to the default attribute, the filter
+will remove the attribute name and value, knowing that the browser
+will infer the intended attribute anyway. For example, the following
+tag:
+</p>
+<pre class="prettyprint">
+ <form method=get>
+</pre>
+<p>
+can be rewritten to:
+</p>
+<pre class="prettyprint">
+ <form>
+</pre>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/elide_attributes.html?ModPagespeed=on&ModPagespeedFilters=elide_attributes">example</a>.
+</p>
+
+<h2>Requirements</h2>
+<p>
+The 'Elide Attributes' filter must be wary of documents with an XHTML
+doctype, as removing the value from a single-valued attribute will
+result in invalid XHTML. The filter attempts to recognize XHTML
+doctype declarations and will disable this rewriting feature in such
+cases.
+</p>
+
+<h2>Risks</h2>
+<p>This filter is considered medium risk. It is safe for most pages, but
+ might break CSS formatting on certain pages that match on default attributes
+ that this filter removes. Further, JavaScript can be written that inspects
+ the DOM looking for the presence of certain attributes. Such JavaScript may
+ behave differently on a page which has removed otherwise unnecessary
+ attributes.</p>
+
+
+</div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-cache-extend-pdfs.html b/doc/filter-cache-extend-pdfs.html
new file mode 100644
index 0000000..2e88695
--- /dev/null
+++ b/doc/filter-cache-extend-pdfs.html
@@ -0,0 +1,83 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Extend Cache PDFs</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Extend Cache PDFs</h1><h2>Configuration</h2>
+<p>
+The 'Extend Cache PDFs' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters extend_cache_pdfs</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters extend_cache_pdfs;</pre>
+</dl>
+in the configuration file.
+
+<h2>Description</h2>
+<p>
+'Extend Cache PDFs' is a version of <a href="filter-cache-extend">Extend
+Cache</a> that acts on PDFs. Unlike 'Extend Cache' it applies not only to
+resources but also to hyperlinks. For example, while 'Extend Cache' would not
+apply to <code><a href="example.jpg"></code>, 'Extend Cache
+PDFs' would apply to <code><a href="example.pdf"></code>.
+</p>
+
+<h2>Operation</h2>
+<p>
+<a href="filter-cache-extend#operation">Extend Cache: Operation</a> describes
+the standard operation of cache extension in PageSpeed. This filter identifies
+PDF URLs by their ".pdf" extension and marks them as eligible for cache
+extension.
+</p>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> for
+cache-extending PDFs
+<a
+href="https://www.modpagespeed.com/examples/extend_cache_pdfs.html?ModPagespeed=on&ModPagespeedFilters=extend_cache_pdfs"
+>in HTML</a>.
+</p>
+
+<h2>Limitations</h2>
+<p>
+In addition to the <a href="filter-cache-extend#limitations">limitations of
+Extend Cache</a>, this filter is limited by its reliance on file extensions for
+identifying potential PDF URLs. PDF resources with URLs ending in something
+other than ".pdf" won't be considered for cache extension.
+</p>
+<h2>Risks</h2>
+<p>
+This filter has the same risks as <a href="filter-cache-extend#risks">Extend
+Cache</a>.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-cache-extend.html b/doc/filter-cache-extend.html
new file mode 100644
index 0000000..82ed930
--- /dev/null
+++ b/doc/filter-cache-extend.html
@@ -0,0 +1,219 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Extend Cache</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Extend Cache</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Extend Cache' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters extend_cache</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters extend_cache;</pre>
+</dl>
+<p>
+in the configuration file. This is equivalent to enabling all three
+of <code>extend_cache_images</code>, <code>extend_cache_scripts</code>,
+and <code>extend_cache_css</code>.
+</p>
+<p>
+Also see: <a href="filter-cache-extend-pdfs">extend_cache_pdfs</a>.
+</p>
+
+<h2>Description</h2>
+<p>
+'Extend Cache' seeks to improve the cacheability of a web page's resources
+without compromising the ability of site owners to change the resources
+and have those changes propagate to users' browsers.
+</p>
+<p>
+This filter is based on the
+<a target="_blank" href="https://developers.google.com/speed/docs/best-practices/caching#LeverageBrowserCaching">
+best practice</a> to optimize caching, as applied to the browser.
+</p>
+
+<h2 id="operation">Operation</h2>
+<p>
+The 'Extend Cache' filter rewrites the URL references in the HTML
+page to include a hash of the resource content (if
+<a href="filter-css-rewrite"><code>rewrite_css</code></a> is enabled
+then image URLs in CSS will also be rewritten). Thus if the site
+owners change the resource content, then the URL for the rewritten
+resource will also change. The old content in the user's browser
+cache will not be referenced again, because it will not match the new name.
+</p>
+<p>
+The 'Extend Cache' filter also rewrites the HTTP header to extend the
+<code>max-age</code> value of the cacheable resource to 31536000 seconds,
+which is one year.
+</p>
+<p>
+For example, for the following HTML tag/HTTP header pair:
+</p>
+<pre class="prettyprint">
+HTML tag : <img src="images/logo.gif">
+HTTP header: Cache-Control:public, max-age=300
+</pre>
+<p>
+PageSpeed will rewrite these into:
+</p>
+<pre class="prettyprint">
+HTML tag : <img src="images/logo.gif.pagespeed.ce.xo4He3_gYf.gif">
+HTTP header: Cache-Control:public, max-age=31536000
+</pre>
+<p>
+PageSpeed uses the origin cache time-to-live (TTL), in this case
+300 seconds, to periodically re-examine the content to see if it's
+changed. If it changes, then the hash of the content will also
+change. Thus it's safe to serve the hashed URL with a long
+timeout—PageSpeed uses one year.
+</p>
+<p>
+If the site owners change the logo, then PageSpeed will notice
+within 5 minutes and begin serving a different URL to users. But if
+the content does not change, then the hash will not change, and the
+copy in each user's browser will still be valid and reachable.
+</p>
+<p>
+Thus the site owners are still in complete control of how rapidly they can
+deploy changes to the site, but this does not affect the effectiveness
+of the browser cache. Decreasing the TTL only affects how often
+PageSpeed will need to re-examine the resource.
+</p>
+<p>
+It should be noted that cache extension is built into other
+PageSpeed filters as well. All filters that rewrite resources
+include a content-hash in the generated URL, and serve the resource
+with a 1-year TTL. The purpose of this filter is to extend cache
+lifetimes for all resources that are not otherwise optimized.
+</p>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> for
+cache-extending resources
+<a href="https://www.modpagespeed.com/examples/extend_cache.html?ModPagespeed=on&ModPagespeedFilters=extend_cache">in HTML</a> and
+<a href="https://www.modpagespeed.com/examples/rewrite_css_images.html?ModPagespeed=on&ModPagespeedFilters=rewrite_css,extend_cache">in CSS</a>.
+</p>
+
+<h2 id="limitations">Limitations</h2>
+<p>
+Cache extension is only applied to resources that are publicly
+cacheable to begin with. Cache extension is not done on resources
+that have <code>Cache-Control: private</code> or <code>Cache-Control:
+nocache</code>.
+</p>
+<p>
+This can be overridden with:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedForceCaching on</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed ForceCaching on;</pre>
+</dl>
+<p>
+This switch is intended for experimental purposes only, to help
+evaluate the benefit of cache extension against the effort of adding
+cache-control headers to resources. Live traffic should not be served
+this way.
+</p>
+<p>
+The following configure file fragment demonstrates how to configure
+caching headers in Apache. This is how the mod_pagespeed_example
+directory is set up.
+</p>
+<pre class="prettyprint lang-sh">
+# These caching headers are set up for the mod_pagespeed example, and
+# also serve as a demonstration of good values to set for the entire
+# site, if it is to be optimized by mod_pagespeed.
+<Directory /var/www/mod_pagespeed_example>
+ # Any caching headers set on HTML are ignored, and all HTML is served
+ # uncacheable. PageSpeed rewrites HTML files each time they are served. The
+ # first time mod_pagespeed sees an HTML file, it generally won't optimize it
+ # fully. It will optimize better after the second view. Caching defeats this
+ # behavior.
+
+ # Images, styles, and JavaScript are all cache-extended for
+ # a year by rewriting URLs to include a content hash. mod_pagespeed
+ # can only do this if the resources are cacheable in the first place.
+ # The origin caching policy, set here to 10 minutes, dictates how
+ # frequently mod_pagespeed must re-read the content files and recompute
+ # the content-hash. As long as the content doesn't actually change,
+ # the content-hash will remain the same, and the resources stored
+ # in browser caches will stay relevant.
+ <FilesMatch "\.(jpg|jpeg|gif|png|js|css)$">
+ Header set Cache-control "public, max-age=600"
+ </FilesMatch>
+</Directory>
+</pre>
+<p>
+The equivalent configuration for Nginx would be:
+<pre class="prettyprint">
+# Make sure this goes after the .pagespeed. location regexp in your
+# configuration file so that .pagespeed. resources don't get this header
+# applied.
+location /mod_pagespeed_example {
+ location ~* \.(jpg|jpeg|gif|png|js|css)$ {
+ add_header Cache-Control "public, max-age=600";
+ }
+}
+</pre>
+
+<h2 id="risks">Risks</h2>
+<p>
+This filter is considered low risk. The rewritten URL will have a different name
+than that of the original URL, however, so JavaScript that uses URLs as
+templates can stop working. For example, consider a site that
+has <code><input type=image src="button.gif"></code> and runs JavaScript
+that turns <code>button.gif</code> into <code>button-hover.gif</code> when the
+user hovers over the button. With cache extension enabled, or any filter that
+changes the URLs of images, PageSpeed would replace the HTML fragment with
+something like <code><input type=image
+src="button.gif.pagespeed.ce.xo4He3_gYf.gif"></code>. If the script was
+coded as "insert '-hover' before the final '.'" then it would construct an
+invalid hover URL of <code>button.gif.pagespeed.ce.xo4He3_gYf-hover.gif</code>.
+If this is a problem on your site, consider <a href="system#ipro">In-Place
+Resource Optimization</a>.
+
+</p>
+<p>
+ When applied to JavaScript files, this filter is sensitive to
+ <a href="restricting_urls#aris"><code
+ >AvoidRenamingIntrospectiveJavascript</code></a>. For example,
+ a JavaScript file that
+ calls <code>document.getElementsByTagName('script')</code> will not be
+ cache-extended.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-canonicalize-js.html b/doc/filter-canonicalize-js.html
new file mode 100644
index 0000000..a2d4ab5
--- /dev/null
+++ b/doc/filter-canonicalize-js.html
@@ -0,0 +1,293 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Canonicalize JavaScript Libraries</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Canonicalize JavaScript Libraries</h1>
+<h2>Configuration</h2>
+<p>
+The 'Canonicalize JavaScript Libraries' filter is enabled by specifying:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters canonicalize_javascript_libraries</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed EnableFilters canonicalize_javascript_libraries;
+
+</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+This filter identifies popular JavaScript libraries that can be replaced with
+ones hosted for free by a JavaScript library hosting service — by default
+the <a href="/speed/libraries/">Google Hosted Libraries</a>. This has several
+benefits:
+<ul>
+ <li>Most important, first-time site visitors can benefit from browser caching,
+since they may have visited other sites making use of the same service to obtain
+the libraries.</li>
+ <li>The JavaScript hosting service acts as a content delivery network for the
+hosted files, reducing load on the server and improving browser load times.</li>
+ <li>There are no charges for the resulting use of bandwidth by site
+visitors.</li>
+ <li>The hosted versions of library code are generally optimized with
+third-party minification tools. These optimizations can make use of
+library-specific annotations or minification settings that aren't portable to
+arbitrary JavaScript code, so the libraries benefit from more aggressive
+optimization than can be provided by PageSpeed.</li>
+</ul>
+<p>
+In Apache the default set of libraries can be found in
+the <code><a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/net/instaweb/genfiles/conf/pagespeed_libraries.conf">pagespeed_libraries.conf</a></code>
+file, which is loaded along with <code>pagespeed.conf</code> when Apache starts
+up. It contains signatures for all the <a href="/speed/libraries/">Google Hosted
+Libraries</a>. In Nginx you need to
+convert <code>pagespeed_libraries.conf</code> from Apache-format to Nginx
+format:
+</p>
+<pre class="prettyprint lang-sh">
+$ scripts/pagespeed_libraries_generator.sh > ~/pagespeed_libraries.conf
+$ sudo mv ~/pagespeed_libraries.conf /path/to/nginx/configuration_files/
+</pre>
+<p>
+You also need to include it in your Nginx configuration by reference:
+</p>
+<pre class="prettyprint lang-sh">
+include pagespeed_libraries.conf;
+</pre>
+<p>
+Don't edit <code>pagespeed_libraries.conf</code>. Local edits will keep you
+from being able to update it when you update PageSpeed. Rather than editing it
+you should add additional libraries to your main configuration file:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint">
+ModPagespeedLibrary 43 1o978_K0_LNE5_ystNklf \
+ //www.modpagespeed.com/rewrite_javascript.js</pre>
+ <dt>Nginx:<dd><pre class="prettyprint">
+pagespeed Library 43 1o978_K0_LNE5_ystNklf
+ //www.modpagespeed.com/rewrite_javascript.js;</pre>
+</dl>
+<p>
+The general format of these entries is:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedLibrary bytes MD5 canonical_url</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed Library bytes MD5 canonical_url;</pre>
+</dl>
+<p>
+Here <code>bytes</code> is the size in bytes of the library <em>after</em>
+minification by PageSpeed, and <code>MD5</code> is the MD5 hash of the
+library after minification. Minification controls for differences in whitespace
+that may occur when the same script is obtained from different
+sources. The <code>canonical_url</code> is the hosting service URL used to
+replace occurrences of the script. Note that the canonical URL in the above
+example is protocol-relative; this means the data will be fetched using the same
+protocol (<code>http</code> or <code>https</code>) as the containing
+page. Because older browsers don't handle protocol-relative URLs reliably,
+PageSpeed resolves a protocol-relative library URL to an absolute URL based
+on the protocol of the containing page. Do not use <code>http</code> canonical
+URLs in configurations that may serve content over <code>https</code>, or the
+rewritten pages will expose your site to attack and trigger a mixed-content
+warning in the browser. Similarly, avoid using <code>https</code> URLs unless
+you know that the resulting library will eventually be fetched from a secure
+page, as SSL negotiation adds overhead to the initial request.
+</p>
+<p>
+Additional library configuration metadata can be generated with the help of
+the <code>pagespeed_js_minify</code> utility installed along with PageSpeed.
+To use this utility, you will need a local copy of the JavaScript code that you
+wish to replace. If this is stored in <code>library.js</code>, you can generate
+<code>bytes</code> and <code>MD5</code> as follows:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >$ pagespeed_js_minify --print_size_and_hash library.js</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >$ cd /path/to/psol/lib/Release/linux/ia32/
+ $ pagespeed_js_minify --print_size_and_hash library.js</pre>
+</dl>
+<p>
+If you're using the <a href="filter-js-minify#new-minifier">new
+javascript minifier</a>, add the <code>--use_experimental_minifier</code>
+argument to <code>pagespeed_js_minify</code>. If you're using the old minifier,
+add <code>--nouse_experimental_minifier</code>. (As of 1.10.33.0,
+<code>--use_experimental_minifier</code> is default. Previously,
+<code>--nouse_experimental_minifier</code> was.)
+The default <code>pagespeed_libraries.conf</code> includes hashes for both
+the old and new minifiers.
+</p>
+<p>
+This filter is based on the best practices of
+<a target="_blank" href="https://developers.google.com/speed/docs/best-practices/caching#LeverageBrowserCaching">
+optimizing browser caching</a>
+and <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload#MinifyJS">reducing payload
+size</a>.
+</p>
+
+<h2>Operation</h2>
+<p>
+In order to identify a library and canonicalize its URL, PageSpeed must of
+course be able to fetch the JavaScript code from the URL on the original page.
+Because library canonicalization identifies libraries solely by their size and
+hash signature, it is not necessary to authorize PageSpeed to fetch content
+from the domain hosting the canonical content itself. This means that it is
+safe to use this filter behind a reverse proxy or in other situations where
+network access by PageSpeed is deliberately restricted. Browsers visiting
+the site will fetch the content from the canonical URL, but PageSpeed itself
+does not need to do so.
+</p>
+
+<h3>Examples</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/canonicalize_javascript_libraries.html?ModPagespeed=on&ModPagespeedFilters=canonicalize_javascript_libraries">example</a>.
+</p>
+<p>
+If the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <script src="jquery_1_8.js">
+ </script>
+ <script src="a.js">
+ </script>
+ <script src="b.js">
+ </script>
+ </head>
+ <body>
+ ...
+ </body>
+</html>
+</pre>
+<p>
+Then, assuming <code>jquery_1_8.js</code> was an unminified copy of the jquery
+library and <code>a.js</code> and <code>b.js</code> contained site-specific code
+that made use of jquery, the page would be rewritten as follows:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js">
+ </script>
+ <script src="a.js">
+ </script>
+ <script src="b.js">
+ </script>
+ </head>
+ <body>
+ ...
+ </body>
+</html>
+</pre>
+<p>
+The library URL has been replaced by a reference to the canonical minified
+version hosted on <code>ajax.googleapis.com</code>. Note that canonical
+libraries do not participate in most other JavaScript optimizations. For
+example, if <a href="filter-js-combine">Combine JavaScript</a> is also enabled,
+the above page will be rewritten as follows:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js">
+ </script>
+ <script src="http://www.example.com/a.js+b.js.pagespeed.jc.zYiUaxFS8I.js">
+ </script>
+ </head>
+ <body>
+ ...
+ </body>
+</html>
+</pre>
+<p>
+The canonical library is <em>not</em> combined with the other two JavaScript
+files, since this would lose the bandwidth and caching benefits of fetching it
+from the canonical URL.
+</p>
+<p>
+If <a href="filter-js-defer">defer_javascript</a> is enabled, <em>and</em> library
+is <em>not</em> tagged with <code>data-pagespeed-no-defer</code>,
+the canonicalized library is deferred.
+</p>
+
+<h2>Requirements</h2>
+<p>
+Only complete, unmodified libraries referenced by <code><script></code>
+tags in the HTML will be rewritten. Libraries that are loaded by other means
+(for example by injecting a loader script) or that have been modified will not
+be canonicalized.
+</p>
+
+<h2>Risks</h2>
+<p>
+You must ensure that you abide by the terms of service of the providers of the
+canonical content before enabling canonicalization. The terms of service for the
+default configuration can be found
+at <a href="/speed/libraries/terms">https://developers.google.com/speed/libraries/terms</a>.
+</p>
+<p>
+The canonical URL refers to a third-party domain; this can cause additional DNS
+lookup latency the first time a library is loaded. This is mitigated by the
+fact that the canonical copy of the data is shared among multiple sites.
+</p>
+<p>
+The initial request for a canonical URL will contain a <code>Referer:</code>
+header with the URL of the referring page. This permits the host of the
+canonical content to see a subset of traffic to your site (the first load of a
+page on your site that contains an identified library by a browser that does not
+already have that library in its cache). The provider should describe how this
+data is used in its terms of service. The terms of service for the default
+configuration can be found at
+<a href="/speed/libraries/terms">https://developers.google.com/speed/libraries/terms</a>.
+Again, this risk is mitigated by the fact that canonical libraries are shared
+among multiple sites; a popular library is likely to already reside in the
+browser cache.
+</p>
+<p>
+Sites serving content on both <code>http</code> and <code>https</code> URLs must
+use protocol-relative canonical URLs as shown <a href="#sample">above</a>.
+Fetching a library insecurely from a secure page exposes a site to attack.
+Fetching a library securely from an ordinary page can increase load time due to
+SSL overheads.
+</p>
+<p>
+It is theoretically possible to craft a JavaScript file whose minified size and
+hash exactly match that of a canonical library, but whose code behaves
+differently. In such a case the library will be replaced with the canonical
+(widely-used) library. This will break the page that contains the reference to
+the crafted JavaScript.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-comment-remove.html b/doc/filter-comment-remove.html
new file mode 100644
index 0000000..8874590
--- /dev/null
+++ b/doc/filter-comment-remove.html
@@ -0,0 +1,129 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Remove Comments</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Remove Comments</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Remove Comments' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters remove_comments</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters remove_comments;</pre>
+</dl>
+<p>
+in the configuration file. To retain comments that have semantic reason to be
+delivered to the browser, you may specify one more wildcard patterns
+using <code>RetainComment</code> directives. For example:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedRetainComment " google_ad_section*"</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed RetainComment " google_ad_section*";</pre>
+</dl>
+</p>
+
+<h2>Description</h2>
+<p>
+The <code>remove_comments</code> filter eliminates HTML comments,
+which are often used to document the code or to comment out
+experiments. Note that this directive applies only to HTML files.
+CSS comments are eliminated with the
+<code>rewrite_css</code> filter, and Javascript comments are
+eliminated with the <code>rewrite_javascript</code> filter.
+</p>
+<p>
+The filter reduces the transfer size of HTML files by removing most HTML
+comments. Depending on the HTML file, this filter can significantly reduce the
+number of bytes transmitted on the network. Also note that
+the <code>RetainComment</code> directive currently only applies to HTML files --
+the wildcard pattern is not currently used for retaining CSS or Javascript
+comments.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+<body>
+<!-- Display the site logo here -->
+<img src="logo.png">
+<!-- Now show the page contents -->
+<div>Some content here</div>
+<!-- Apply IE-specific CSS -->
+<!-- [if IE ]>
+<link href="iecss.css" rel="stylesheet" type="text/css">
+<![endif]-->
+<!-- google_ad_section_end -- retained due to RetainComment directive -->
+</body>
+</html>
+</pre>
+<p>
+Then PageSpeed, with the above directives specified, will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+<body>
+<img src="logo.png">
+<div>Some content here</div>
+<!-- [if IE ]>
+<link href="iecss.css" rel="stylesheet" type="text/css">
+<![endif]-->
+<!-- google_ad_section_end -- retained due to RetainComment directive -->
+</body>
+</html>
+</pre>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/remove_comments.html?ModPagespeed=on&ModPagespeedFilters=remove_comments">example</a>.
+</p>
+
+<h2>Notes</h2>
+<p>
+The "Remove Comments" filter is aware of
+<a href="http://msdn.microsoft.com/en-us/library/ms537512(VS.85).aspx">Internet Explorer conditional comments</a> and does not remove them.
+</p>
+
+<h2>Risks</h2>
+<p>
+This filter is low risk for most web pages. Some web pages use comments to
+embed data or JavaScript, in order to reduce the parse time of the HTML
+document. Such pages sould disable this filter, as it will remove the
+comments containing the data or JavaScript that is needed by these web
+pages.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-convert-meta-tags.html b/doc/filter-convert-meta-tags.html
new file mode 100644
index 0000000..dd29075
--- /dev/null
+++ b/doc/filter-convert-meta-tags.html
@@ -0,0 +1,78 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Convert Meta Tags</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Convert Meta Tags</h1>
+<h2>Configuration</h2>
+<p>
+The 'Convert Meta Tags' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters convert_meta_tags</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters convert_meta_tags;</pre>
+</dl>
+<p>
+in the configuration file, but it is also enabled automatically by the core
+filter set.
+</p>
+
+<h2>Description</h2>
+<p>
+The 'Convert Meta Tags' filter adds a response header that matches each meta
+tag with an http-equiv attribute. For example, HTML
+<pre class="prettyprint"
+ ><meta http-eqiv="Content-Type" content="text/html; charset=UTF-8"></pre>
+would add an HTTP header:
+<pre class="prettyprint"
+ >Content-Type: text/html; charset=UTF-8</pre>
+in the response headers.
+</p>
+<p>
+The original tag is left unchanged.
+</p>
+<p>
+Certain http-equiv meta tags, specifically those that specify content-type,
+require a browser to reparse the html document if they do not match the headers.
+By ensuring that the headers match the meta tags, these reparsing delays are
+avoided.
+</p>
+
+<h2>Risks</h2>
+<p>
+This filter is considered minimal risk because at this time,
+Content-Type is the only <code>http-equiv</code> value that is transformed into
+an HTTP header. Other http-equiv values have been found to have unexpected semantic
+implications when transformed to HTTP.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-above-scripts.html b/doc/filter-css-above-scripts.html
new file mode 100644
index 0000000..b4d2e23
--- /dev/null
+++ b/doc/filter-css-above-scripts.html
@@ -0,0 +1,152 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Move CSS Above Scripts</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Move CSS Above Scripts</h1>
+
+
+<h2>Configuration</h2>
+<p>
+ The 'Move CSS Above Scripts' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters move_css_above_scripts</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters move_css_above_scripts;</pre>
+</dl>
+<p>
+ in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+ 'Move CSS Above Scripts' seeks to make sure scripts do not block the
+ loading of CSS resources.
+</p>
+<p>
+ This is based on the
+ <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt#PutStylesBeforeScripts">
+ best practice for downloading resources early.
+ </a>
+</p>
+
+<h2>Operation</h2>
+<p>
+ The 'Move CSS Above Scripts' filter operates only on CSS
+ <code><link></code> and <code><style></code> tags found after the
+ first <code><script></code> tag and moves these tags above the first
+ <code><script></code>.
+</p>
+<p>
+ For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ </head>
+ <body>
+ <script src="script.js" type="text/javascript"></script>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ <style type="text/css">
+ .foo { color: red; }
+ </style>
+ <link rel="stylesheet" type="text/css" href="styles/all_styles.css">
+ </body>
+</html>
+</pre>
+<p>
+ Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ </head>
+ <body>
+ <style type="text/css">
+ .foo { color: red; }
+ </style>
+ <link rel="stylesheet" type="text/css" href="styles/all_styles.css">
+ <script src="script.js" type="text/javascript"></script>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+
+<p>
+ In some browsers the original version will not even download the CSS file
+ until the JavaScript has been downloaded and run. This transformation will
+ make sure the CSS file is loaded first.
+</p>
+<p class="note">
+ Note: You may also want to enable
+ the <a href="filter-css-to-head">move_css_to_head</a> filter to avoid a flash
+ of unstyled content. When both filters are enabled, stylesheets are moved
+ into the head and above the first script.
+</p>
+
+<h3>Example</h3>
+<p>
+ You can see the filter in action at <code>www.modpagespeed.com</code> on this
+ <a href="https://www.modpagespeed.com/examples/move_css_above_scripts.html?ModPagespeed=on&ModPagespeedFilters=move_css_above_scripts">example</a>.
+</p>
+
+<h2>Limitations</h2>
+<p>
+ This filter operates within the scope of a "flush window". Specifically,
+ large, or dynamically generated HTML files may be "flushed" by the
+ resource generator before they are complete. If the filter
+ encounters a flush after the first <code><script></code> tag,
+ subsequently encountered CSS elements will not be moved above it.
+</p>
+
+<h2>Risks</h2>
+<p>
+ This filter is considered low risk. However, JavaScript that is
+ executed before a CSS element will see a different view of the DOM in
+ the presence of this rewriter: the CSS element will now be in the head.
+ If there is such JavaScript embedded in the middle of a page then this
+ rewriter may change its behavior.
+</p>
+<p>
+ This filter may slow down your webpages for some browsers. Just as JavaScript
+ can block download of CSS in some browsers, some others will not execute
+ JavaScript until preceding CSS has been rendered. This filter is currently
+ considered experimental while we measure its effectiveness.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-combine.html b/doc/filter-css-combine.html
new file mode 100644
index 0000000..5992826
--- /dev/null
+++ b/doc/filter-css-combine.html
@@ -0,0 +1,216 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Combine CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Combine CSS</h1>
+
+
+<h2>Configuration</h2>
+<p>
+The 'Combine CSS' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters combine_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters combine_css;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+'Combine CSS' seeks to reduce the number of HTTP requests made by a browser
+during page refresh by replacing multiple distinct CSS files with a single CSS
+file, containing the contents of all of them. This is particularly important in
+old browsers, that were limited to two connections per domain. In addition to
+reduced overhead for HTTP headers and communications warm-up, this approach
+works better with TCP/IP slow-start, increasing the effective payload bit-rate
+through the browser's network connection.
+</p>
+<p>
+This <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt#CombineExternalCSS">practice</a>
+reduces the number of round-trip times.
+</p>
+
+<h2>Operation</h2>
+<p>
+The "CSS Combine" filter finds all CSS <code><link></code> tags. If there
+was more than one in a flush window, it removes each of those links and replaces
+them with a single <code><link></code> to the merged document, which it
+places wherever the first CSS <code><link></code> originally was.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <link rel="stylesheet" type="text/css" href="styles/yellow.css">
+ <link rel="stylesheet" type="text/css" href="styles/blue.css">
+ <link rel="stylesheet" type="text/css" href="styles/big.css">
+ <link rel="stylesheet" type="text/css" href="styles/bold.css">
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <link rel="stylesheet" type="text/css" href="styles/yellow.css+blue.css+big.css+bold.css.pagespeed.cc.xo4He3_gYf.css">
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/combine_css.html?ModPagespeed=on&ModPagespeedFilters=combine_css">example</a>.
+</p>
+
+<h2>Parameters that affect CSS optimization</h2>
+
+<h3 id="MaxCombinedCssBytes">MaxCombinedCssBytes</h3>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMaxCombinedCssBytes MaxBytes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MaxCombinedCssBytes MaxBytes;</pre>
+</dl>
+<p>
+<code>MaxBytes</code> is the maximum size in bytes of the combined CSS files.
+CSS files larger than <code>MaxBytes</code> will be kept intact;
+other CSS files will be combined into one or more files, each being no more
+than <code>MaxBytes</code> in size. The current default value for
+<code>MaxBytes</code> is -1 (unlimited).
+</p>
+
+<h2>Limitations</h2>
+<p>The CSS Combine filter operates within the scope of a "flush window".
+Specifically, large, or dynamically generated HTML files may be
+"flushed" by the resource generator before they are complete. When the
+CSS combiner encounters a flush, it will emit all CSS combinations seen
+up to the point of the flush. After the flush, it will begin collecting
+a new CSS combination.
+</p>
+<p>This filter generates URLs that are essentially the concatenation
+of the URLs of all the CSS files being combined. The maximum URL size
+is generally limited to about 2k characters due to IE:
+See <a href="http://support.microsoft.com/kb/208427/EN-US"
+>http://support.microsoft.com/kb/208427/EN-US</a>. Apache servers by
+default impose a further limitation of about 250 characters per URL segment
+(text between slashes). PageSpeed circumvents this limitation when it runs
+within Apache, but if you employ proxy servers in your path you may need to
+re-impose it by overriding the setting here. The default setting is 1024.</p>
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedMaxSegmentLength 250</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed MaxSegmentLength 250;</pre>
+</dl>
+
+<h3 id="permit-ids-for-css-combining">Combining Resources with IDs</h3>
+<p class="note"><strong>Note: New feature as of 1.12.34.1</strong></p>
+
+<p>
+ By default PageSpeed won't combine CSS files that have <code>id</code>
+ attributes, because this often indicates that the site designer intended to
+ reference them in javascript. However, some content management systems,
+ including WordPress, put <code>id</code>s on all stylesheets for clarity. To
+ enable combining these files, you can provide one or more wildcards. For
+ example, this would mark stylesheets with ids starting with <code>font</code>
+ as eligible for combining:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedPermitIdsForCssCombining font*</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed PermitIdsForCssCombining font*;</pre>
+</dl>
+
+<h2>Requirements</h2>
+<p>
+The 'Combine CSS' filter may need to <em>absolutify</em> relative
+URLs, if rewriting the CSS causes the path to be moved. The filter
+will not merge together resources from multiple distinct domains, even
+if those domains are each authorized by <code>Domain</code>.
+It <strong>will</strong> merge together resources from multiple
+distinct domains that have been mapped together via
+<code>MapRewriteDomain</code>.
+</p>
+<p>
+By default, the filter will combine together CSS files from different
+paths, placing the combined element at the lowest level common to both
+origins. In some cases, this may be undesirable. You can turn off the
+behavior with:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCombineAcrossPaths off</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CombineAcrossPaths off;</pre>
+</dl>
+<p>
+The filter will maintain the order of the CSS contents, as class order can be
+significant.
+</p>
+<p>
+IE Directives containing CSS links form a "barrier" for the CSS combiner.
+Multiple CSS elements found before an IE directive are combined together
+immediately before the IE directive. Multiple CSS elements found after are
+also combined, but the combination does not span across the IE directive, as
+that would affect the order that the browser sees the CSS elements.
+</p>
+
+<h2>Risks</h2>
+<p>
+This filter is considered low risk. However, JavaScript can be written that
+walks the DOM looking for <code><link></code> entries with certain
+syntax. Such JavaScript may behave differently on a page which has modified
+CSS links in this way.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-inline-google-fonts.html b/doc/filter-css-inline-google-fonts.html
new file mode 100644
index 0000000..b4aeff0
--- /dev/null
+++ b/doc/filter-css-inline-google-fonts.html
@@ -0,0 +1,162 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Inline Google Fonts API CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Inline Google Fonts API CSS</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Inline Google Fonts API CSS' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters inline_google_font_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters inline_google_font_css;</pre>
+</dl>
+<p>
+in the configuration file. You also need to
+enable <a href="https_support#https_fetch">HTTPS Fetching</a> if your pages load
+fonts over HTTPS:
+
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedFetchHttps enable</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed FetchHttps enable;</pre>
+</dl>
+
+</p>
+
+<p>As of 1.9.32.6, the size limit for this filter is controlled as follows:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedGoogleFontCssInlineMaxBytes bytes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed GoogleFontCssInlineMaxBytes bytes;</pre>
+</dl>
+
+<p>In older versions, the filter used same size limits as the main CSS filter:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCssInlineMaxBytes bytes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CssInlineMaxBytes bytes;</pre>
+</dl>
+<p>
+This is the maximum size in bytes of any CSS file that will be inlined.
+</p>
+<h2>Description</h2>
+<p>
+The "Inline Google Fonts API CSS" filter reduces the number of requests made by
+a web page that uses the Google Fonts API by inlining the small loader CSS
+into the webpage. Note that because the loader CSS is browser-specific, this
+feature is not currently compatible with downstream caching being on or
+<code>ModifyCachingHeaders</code> being off.
+</p>
+<h2>Operation</h2>
+<p>
+When the 'Inline Google Fonts API CSS' filter is enabled, the contents of the
+small external CSS resources produced to load the fonts are written directly
+into the HTML document; the browser does not need to request those CSS
+resources independently.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <title>inline_google_font_css example</title>
+ <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Roboto">
+ <style>
+ body {
+ font-family: 'Roboto', sans-serif;
+ }
+ </style>
+ </head>
+ <body>
+ The font should be slightly more robotic.
+ </body>
+</html>
+</pre>
+<p>
+Then, a visitor using a browser for which woff fonts are preferred may see
+something like:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <title>inline_google_font_css example</title>
+ <style>@font-face {
+ font-family: 'Roboto';
+ font-style: normal;
+ font-weight: 400;
+ src: local('Roboto Regular'), local('Roboto-Regular'), url(http://themes.googleusercontent.com/static/fonts/roboto/v9/abcd.woff) format('woff');
+ }
+ </style>
+ <style>
+ body {
+ font-family: 'Roboto', sans-serif;
+ }
+ </style>
+ </head>
+ <body>
+ The font should be slightly more robotic.
+ </body>
+</html>
+</pre>
+<p>
+This eliminates the browser request to <code>fonts.googleapis.com</code> and
+potentially the need for the browser to perform a DNS lookup and connect to
+that host entirely.
+
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/inline_google_font_css.html?PageSpeed=on&PageSpeedFilters=inline_google_font_css">example</a>.
+</p>
+
+<h2>Risks</h2>
+<p>
+You must ensure that you abide by
+<a href="https://developers.google.com/fonts/terms">Google Fonts API Terms of Service</a>.
+Note that enabling this filter will cause some requests to be sent to
+the API from your server (rather than just the visitor), which may be logged
+per the Fonts API Terms of Service.
+</p>
+
+<p>
+The filter is low to moderate risk. It should be safe for most pages, but it
+could potentially break scripts that walk the DOM looking
+for and examining <code><link></code> or <code><style></code> tags.
+</p>
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-inline-import.html b/doc/filter-css-inline-import.html
new file mode 100644
index 0000000..8eab835
--- /dev/null
+++ b/doc/filter-css-inline-import.html
@@ -0,0 +1,112 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Inline @import to Link</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Inline @import to Link</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Inline @import to Link' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters inline_import_to_link</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters inline_import_to_link;</pre>
+</dl>
+in the configuration file.
+</p>
+<h2>Description</h2>
+<p>
+The "Inline @import to Link" filter converts a <code><style></code> tag
+consisting of only <code>@import</code> statements into the corresponding
+<code><link></code> tags. This conversion does not itself result in any
+significant optimization, rather its value lies in that it enables optimization
+of the linked-to CSS files by later filters, in particular the combine_css,
+rewrite_css, inline_css, and extend_cache filters.
+</p>
+<h2>Operation</h2>
+<p>
+This filter inspects the contents of all <code><style></code> tags and
+converts the tag if all the following conditions are met:</p>
+<ul>
+<li>Either the <code><style></code> tag has no <code>type</code>
+ attribute or the <code>type</code> attribute has the value
+ "text/css".</li>
+<li>The contents comprise one or more valid <code>@import</code> statements,
+ and no other statements.</li>
+<li>None of the imported URLs are empty.</li>
+<li>The <code><style></code> tag has neither an <code>href</code> nor a
+ <code>rel</code> attribute (which would make it invalid anyway).</li>
+<li>If the <code><style></code> tag has a <code>media</code> attribute
+ and the <code>@import</code> statement specifies media after the URL, then
+ the media types listed must be the same. They do not have to be in the same
+ order, and blank media types are ignored.</li>
+</ul>
+<p>
+If all these conditions are met, the <code><style></code> tag and its
+contents are replaced with a <code><link></code> tag for each
+<code>@import</code>, with:</p>
+<ul>
+<li>Attributes from the <code><style></code> tag copied to the
+ <code><link></code> tag.</li>
+<li>An <code>href</code> attribute with value of the imported URL.</li>
+<li>A <code>rel</code> attribute with value of "stylesheet".</li>
+<li>If the <code><style></code> tag did not have a <code>media</code>
+ attribute but the <code>@import</code> specified media after the URL, then
+ a <code>media</code> attribute with value of the media specified after the
+ URL.</li>
+</ul>
+<p>
+For example, if the <code><style></code> tag looks like this:
+</p>
+<pre class="prettyprint">
+<style type="text/css" media="screen">@import url(http://www.example.com/style.css);</style>
+</pre>
+<p>
+Then PageSpeed will convert it to:
+<pre class="prettyprint">
+<link type="text/css" media="screen" rel="stylesheet" href="http://www.example.com/style.css"/>
+</pre>
+
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/inline_import_to_link.html?ModPagespeed=on&ModPagespeedFilters=inline_import_to_link">example</a>.
+</p>
+
+<h2>Risks</h2>
+<p>
+This filter is considered minimal risk.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-inline.html b/doc/filter-css-inline.html
new file mode 100644
index 0000000..604dcf5
--- /dev/null
+++ b/doc/filter-css-inline.html
@@ -0,0 +1,157 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Inline CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Inline CSS</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Inline CSS' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters inline_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters inline_css;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+<p>When this filter is enabled, you may also enable the following setting:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCssInlineMaxBytes bytes</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CssInlineMaxBytes bytes;</pre>
+</dl>
+<p>
+This is the maximum size in bytes of any CSS file that will be inlined.
+</p>
+<h2>Description</h2>
+<p>
+The "Inline CSS" filter reduces the number of requests made by a web page by
+inserting the contents of small external CSS resources directly into the HTML
+document. This can reduce the time it takes to display content to the user,
+especially in older browsers.
+</p>
+<h2>Operation</h2>
+<p>
+When the 'Inline CSS' filter is enabled, The contents of small external CSS
+resources are written directly into the HTML document; therefore the browser
+does not request those CSS resources independently.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <link rel="stylesheet" href="small.css">
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+And the resource <code>small.css</code> is like this:
+<pre class="prettyprint">
+ .yellow {background-color: yellow;}
+ .blue {color: blue;}
+ .big { font-size: 8em; }
+ .bold { font-weight: bold; }
+</pre>
+<p>
+Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style>
+ .yellow {background-color: yellow;}
+ .blue {color: blue;}
+ .big { font-size: 8em; }
+ .bold { font-weight: bold; }
+ </style>
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+This eliminates the browser request to <code>small.css</code> by placing its
+contents inline in the HTML document.
+
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/inline_css.html?ModPagespeed=on&ModPagespeedFilters=inline_css">example</a>.
+</p>
+
+<h2>Note</h2>
+<p>
+CSS may contain URLs that are relative to the location of the CSS
+file. To avoid breaking such URLs, the 'Inline CSS' filter will attempt to
+rewrite them into absolute URLs when it performs the inlining.
+</p>
+
+<h2>Requirements</h2>
+<p>
+There is a tradeoff here between requests and cacheability: including the CSS
+directly in the HTML avoids making an additional request to the external CSS
+resource, but if the CSS file is large (and doesn't change often), it may be
+better to keep it separate from the HTML so that it can be cached by the
+browser. Thus, the Inline CSS filter will only inline CSS files below a
+certain size threshold, which can be adjusted using the
+<code>CssInlineMaxBytes</code> directive.
+</p>
+<p>
+It is possible for CSS files to contain small snippets of JavaScript code, at
+least for certain browsers. To avoid opening up cross-domain scripting
+vulnerabilities, the Inline CSS filter will only inline an external CSS file if
+it is being served from the same domain as the HTML file into which it is to be
+inlined.
+</p>
+
+<h2>Risks</h2>
+<p>
+The 'Inline CSS' filter is low to moderate risk. It should be safe for most
+pages, but it could potentially break scripts that walk the DOM looking for
+and examining <code><link></code> or <code><style></code> tags.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-outline.html b/doc/filter-css-outline.html
new file mode 100644
index 0000000..295ef4c
--- /dev/null
+++ b/doc/filter-css-outline.html
@@ -0,0 +1,182 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Outline CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Outline CSS</h1>
+
+<h2>Configuration</h2>
+<p>
+The 'Outline CSS' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters outline_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters outline_css;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+This filter is an <strong>experimental</strong> filter which takes inline
+CSS and puts it in an external resource.
+</p>
+
+<h2>Operation</h2>
+<p>
+The 'Outline CSS' filter outlines all CSS that is larger than a minimum byte
+threshold. The threshold can be set by adding/changing the line:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedCssOutlineMinBytes 3000</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed CssOutlineMinBytes 3000;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style type="text/css">
+ .yellow {background-color: yellow;}
+ .blue {color: blue;}
+ .big { font-size: 8em; }
+ .bold { font-weight: bold; }
+ ...
+ </style>
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <link rel="stylesheet" type="text/css" href="of.HASH.css">
+ </head>
+ <body>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+<p>
+And a new CSS file (<code>of.HASH.css</code>) will be:
+</p>
+<pre class="prettyprint">
+ .yellow {background-color: yellow;}
+ .blue {color: blue;}
+ .big { font-size: 8em; }
+ .bold { font-weight: bold; }
+ ...
+</pre>
+
+<h3>Example</h3>
+<p>
+You can see the filter in action at <code>www.modpagespeed.com</code> on this
+<a href="https://www.modpagespeed.com/examples/outline_css.html?ModPagespeed=on&ModPagespeedFilters=outline_css">example</a>.
+</p>
+
+<h2>Pros and Cons</h2>
+<p>
+This could be advantageous if:
+</p>
+<ol>
+ <li>The CSS does not change much but the HTML does, then we can cache the
+ CSS.</li>
+ <li>One has many websites with the same inlined CSS, it will be outlined
+ to a consistent name and thus will be cached more or</li>
+ <li>The inline CSS is very long, in which case, outlining it will cause it
+ to be loaded in parallel with the HTML doc.</li>
+</ol>
+<p>
+However, for some websites it will be dis-advantageous because it will:
+</p>
+<ol>
+ <li>Create an extra HTTP request.</li>
+ <li>Tie up one of the connections this domain, which could have been used to
+ fetch the actually cacheable external resources.</li>
+</ol>
+
+<h2>Requirements</h2>
+<p>
+Outline filters can currently only run on single-server environments
+because the resource can only be fetched from a server after that server
+has rewritten the HTML page. If a different server rewrote the HTML page,
+then this sever will not have the information needed to create the resource.
+This could be by a network database shared between servers.
+</p>
+<p>
+The Outline CSS filter may need to <em>"absolutify"</em> relative URLs, if
+it is outlined to a different directory than the original HTML.
+</p>
+<p>
+The Outline CSS filter will maintain the order of the CSS contents, as
+class order can be significant.
+</p>
+
+<h2>Risks</h2>
+<p>
+The 'Outline CSS' filter is considered low risk. However, JavaScript can be
+written that walks the DOM looking for <code><link></code> or
+<code><style></code> tags with certain syntax. Such JavaScript
+may behave differently on a page which has added
+<code><link></code> or removed <code><style></code> tags
+in this way.
+</p>
+<p>
+Additionally we have reproduced an obscure difference that sometimes occurs
+on WebKit-based browsers (such as Safari, Chrome and the Android browser).
+As of January 2011, WebKit does not delay JavaScript evaluation for
+external CSS loading (See
+<a href="https://webkit.org/b/24898">https://webkit.org/b/24898</a>).
+So some CSS attributes, when outlined, can cause slightly different
+rendering depending on whether or not the CSS file is loaded before or
+after the JavaScript is executed.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-rewrite.html b/doc/filter-css-rewrite.html
new file mode 100644
index 0000000..366fe28
--- /dev/null
+++ b/doc/filter-css-rewrite.html
@@ -0,0 +1,215 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Rewrite CSS</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Rewrite CSS</h1>
+
+<h2 id="configuration">Configuration</h2>
+<p>
+ The 'Rewrite CSS' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters rewrite_css</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters rewrite_css;</pre>
+</dl>
+<p>
+ in the configuration file. To enable fallback rewriting on CSS we cannot
+ parse, also specify:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters fallback_rewrite_css_urls</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters fallback_rewrite_css_urls;</pre>
+</dl>
+
+<h2>Description</h2>
+<p>
+ This filter parses linked and inline CSS, rewrites the images found
+ and minifies the CSS. The filter works on CSS found in
+ <code><style></code> blocks and <code><link></code> refs.
+</p>
+<p>
+ Many images are referenced from CSS rather than HTML. If
+ <a href="reference-image-optimize#rewrite_images"
+ ><code>rewrite_images</code></a>,
+ <a href="reference-image-optimize#recompress_images"
+ ><code>recompress_images</code></a>,
+ <a href="reference-image-optimize#recompress_jpeg"
+ ><code>recompress_jpeg</code></a>,
+ <a href="reference-image-optimize#recompress_png"
+ ><code>recompress_png</code></a>,
+ <a href="reference-image-optimize#recompress_webp"
+ ><code>recompress_webp</code></a>,
+ <a href="reference-image-optimize#convert_gif_to_png"
+ ><code>convert_gif_to_png</code></a>,
+ <a href="reference-image-optimize#convert_jpeg_to_webp"
+ ><code>convert_jpeg_to_webp</code></a>,
+ <a href="reference-image-optimize#convert_png_to_jpeg"
+ ><code>convert_png_to_jpeg</code></a>,
+ or <a href="filter-cache-extend"
+ ><code>extend_cache</code></a>
+ are enabled this filter finds and rewrites those images, saving bytes
+ and extending cache lifetimes.
+</p>
+<p>
+ The CSS parser cannot parse some CSS3 or proprietary CSS extensions.
+ If <code>fallback_rewrite_css_urls</code> is not enabled, these
+ CSS files will not be rewritten at all.
+ If the <code>fallback_rewrite_css_urls</code> filter is enabled, a
+ fallback method will attempt to rewrite the URLs in the CSS file,
+ even if the CSS cannot be successfully parsed and minified.
+</p>
+<p>
+ Minification can drastically reduce the byte count in common CSS by
+ stripping all comments and most whitespace and shortening color names.
+ This filter can be used to avoid the extra step of minifying CSS by hand
+ when constructing and maintaining a site.
+ This <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload#MinifyCSS">practice</a>
+ reduces the payload size.
+</p>
+
+<h2>Example</h2>
+<p>
+ For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style>
+ body { background-image: url("foo.png"); }
+ /* This comment will be stripped */
+ #iddy, .anotherId {
+ border: solid 1px #cccccc;
+ padding: 1.2em;
+ float: left;
+ color:##ff0000;
+ }
+ </style>
+ <link rel="stylesheet" type="text/css" href="extStyle.css">
+ </head>
+ <body>
+ Wow, <div class="classy" id="iddy">
+ CSS is <span>stylin'</span>.</div>
+ </body>
+</html>
+</pre>
+<p>
+ With the following in <code>extStyle.css</code>:
+</p>
+<pre class="prettyprint">
+ div.classy span, div.classy img {
+ display: block;
+ border: none !important;
+ background: none !important;
+ }
+</pre>
+<p>
+ Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style>body{background-image:url(xfoo.png.pagespeed.ic.HASH.png}#iddy,#anotherId{border:solid 1px #ccc;padding:1.2em;float:left;color:red}</style>
+ <link rel="stylesheet" type="text/css" href="I.extStyle.css.pagespeed.cf.HASH.css">
+ </head>
+ <body>
+ Wow, <div class="classy" id="iddy">
+ CSS is <span>stylin'</span>.</div>
+ </body>
+</html>
+</pre>
+<p>
+ And the rewritten file <code>I.extStyle.css.pagespeed.cf.HASH.css</code> will
+ contain:
+</p>
+<pre class="prettyprint">
+ dif.classy span,div.classy img{display:block;border:none!important;background:none!important}
+</pre>
+
+<h3>Online Example</h3>
+<p>
+ You can see the filter in action at <code>www.modpagespeed.com</code> for
+ <a href="https://www.modpagespeed.com/examples/rewrite_css.html?ModPagespeed=on&ModPagespeedFilters=rewrite_css">CSS minification</a>,
+ <a href="https://www.modpagespeed.com/examples/rewrite_css_images.html?ModPagespeed=on&ModPagespeedFilters=rewrite_css,extend_cache">cache-extending images in CSS</a>,
+ <a href="https://www.modpagespeed.com/examples/rewrite_css_images.html?ModPagespeed=on&ModPagespeedFilters=rewrite_css,rewrite_images">rewriting images in CSS</a> and
+ <a href="https://www.modpagespeed.com/examples/fallback_rewrite_css_urls.html?ModPagespeed=on&ModPagespeedFilters=fallback_rewrite_css_urls,rewrite_css,rewrite_images">fallback rewriting of images in CSS</a>.
+</p>
+
+<h2>Requirements</h2>
+<p>
+ Only CSS referenced by <code><style></code> and <code><link>
+ </code> tags is rewritten. For example, style attributes of HTML elements
+ are not rewritten. Enable <a href="filter-rewrite-style-attributes">
+ <code>rewrite_style_attributes</code></a> to rewrite these as well.
+</p>
+<p>
+ Not all CSS3 or proprietary constructs are parsed. When unhandled syntax
+ is present and the file cannot be parsed completely, the URLs in the CSS
+ can still be rewritten by the <code>fallback_rewrite_css_urls</code> filter.
+ However the CSS will not be minified.
+</p>
+
+<h2 id="risks">Risks</h2>
+<p>
+ CSS minification is considered moderate risk.
+</p>
+<p>
+ Specifically, there is an outstanding bug that the CSS parser can silently
+ lose data on malformed CSS. This only applies to malformed CSS or CSS that
+ uses proprietary extensions. All known examples have been fixed, but there
+ may be more examples not discovered yet. Without this the risk would be low.
+</p>
+<p>
+ Some JavaScript code depends upon the exact URLs of resources. When we minify
+ CSS we will change the leaf name of the file (although leave it in the same
+ directory). This could break such JavaScript.
+</p>
+
+<h2>Troubleshooting</h2>
+<p>
+ To troubleshoot why CSS is not minified, you can use the standalone binary
+ <code>css_minify_main</code>. It's shipped with mod_pagespeed, so
+ <a href="build_mod_pagespeed_from_source#debug-css"
+ >build it from source</a> and then run:
+</p>
+<pre>
+ ./out/Release/css_minify_main FILENAME.css > REWRITTEN.css
+</pre>
+<p>
+ The rewritten version is piped to <code>stdout</code> and the errors
+ encountered are piped to <code>stderr</code>. These error messages should
+ be helpful in figuring out what aspects of the CSS file could not be parsed.
+</p>
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-css-to-head.html b/doc/filter-css-to-head.html
new file mode 100644
index 0000000..07a34a2
--- /dev/null
+++ b/doc/filter-css-to-head.html
@@ -0,0 +1,143 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Move CSS to Head</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Move CSS to Head</h1>
+
+
+<h2>Configuration</h2>
+<p>
+ The 'Move CSS to head' filter is enabled by specifying:
+</p>
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters move_css_to_head</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters move_css_to_head;</pre>
+</dl>
+<p>
+ in the configuration file.
+</p>
+
+<h2>Description</h2>
+<p>
+ 'Move CSS to head' seeks to reduce the number of times the browser must
+ re-flow the document by ensuring that the CSS styles are all parsed in
+ the head, before any body elements are introduced.
+</p>
+<p>
+ This is based on the
+ <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rendering#PutCSSInHead">
+ best practice for optimizing browser rendering.
+ </a>
+</p>
+
+<h2>Operation</h2>
+<p>
+ The 'Move CSS to head' filter operates only on CSS
+ <code><link</code> and <code><style></code> tags found after the
+ <code></head></code> and moves these links back into the
+ <code><head></code> ... <code></head></code> section.
+</p>
+<p>
+For example, if the HTML document looks like this:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ </head>
+ <body>
+ <script src="script.js" type="text/javascript"></script>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ <style type="text/css">
+ .foo { color: red; }
+ </style>
+ <link rel="stylesheet" type="text/css" href="styles/all_styles.css">
+ </body>
+</html>
+</pre>
+<p>
+ Then PageSpeed will rewrite it into:
+</p>
+<pre class="prettyprint">
+<html>
+ <head>
+ <style type="text/css">
+ .foo { color: red; }
+ </style>
+ <link rel="stylesheet" type="text/css" href="styles/all_styles.css">
+ </head>
+ <body>
+ <script src="script.js" type="text/javascript"></script>
+ <div class="blue yellow big bold">
+ Hello, world!
+ </div>
+ </body>
+</html>
+</pre>
+
+<p>
+ In some browsers, the original version will flash quickly as the
+ browser will render the "Hello, world!" text before it sees the style
+ tags providing definitions for the CSS classes. This transformation
+ will eliminate that flash, but the end result will be the same.
+</p>
+
+<h3>Example</h3>
+<p>
+ You can see the filter in action at <code>www.modpagespeed.com</code> on this
+ <a href="https://www.modpagespeed.com/examples/move_css_to_head.html?ModPagespeed=on&ModPagespeedFilters=move_css_to_head">example</a>.
+</p>
+
+<h2>Limitations</h2>
+<p>
+ This filter operates within the scope of a "flush window". Specifically,
+ large, or dynamically generated HTML files may be "flushed" by the
+ resource generator before they are complete. If the filter
+ encounters a flush after the end of the <code><head></code> section,
+ subsequently encountered CSS elements will not be moved into the
+ <code><head></code> section.
+</p>
+
+<h2>Risks</h2>
+<p>
+ This filter is considered low risk. However, JavaScript that is
+ executed before a CSS element will see a different view of the DOM in
+ the presence of this rewriter: the CSS element will now be in the head.
+ If there is such JavaScript embedded in the middle of a page then this
+ rewriter may change its behavior.
+</p>
+
+
+ </div>
+ <!--#include virtual="_footer.html" -->
+ </body>
+</html>
diff --git a/doc/filter-dedup-inlined-images.html b/doc/filter-dedup-inlined-images.html
new file mode 100644
index 0000000..f86e240
--- /dev/null
+++ b/doc/filter-dedup-inlined-images.html
@@ -0,0 +1,110 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Deduplicate Inlined Images</title>
+ <link rel="stylesheet" href="doc.css">
+ </head>
+ <body>
+<!--#include virtual="_header.html" -->
+
+
+ <div id=content>
+<h1>Deduplicate Inlined Images</h1>
+<h2>Configuration</h2>
+<p>
+ The 'Deduplicate Inlined Images' filter is enabled by specifying:
+<dl>
+ <dt>Apache:<dd><pre class="prettyprint"
+ >ModPagespeedEnableFilters dedup_inlined_images</pre>
+ <dt>Nginx:<dd><pre class="prettyprint"
+ >pagespeed EnableFilters dedup_inlined_images;</pre>
+</dl>
+<p>
+in the configuration file.
+</p>
+
+<h2>Objective</h2>
+<p>
+ Reduce the transfer size of HTML files by eliminating redundant image data
+ URLs.
+</p>
+
+<h2>PageSpeed Rule</h2>
+<p>
+ This rewriter implements the PageSpeed rule for
+ <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/payload#CompressImages">optimizing
+ images</a>.
+</a>
+</p>
+
+<h2>Description</h2>
+<p>
+ dedup_inlined_images replaces repeated inlined images with JavaScript
+ that loads the image from the first occurence of the image. If the first
+ image doesn't have an <code>id</code>, one is generated and added to it.
+</p>
+
+<h2>Operation</h2>
+<p>
+ dedup_inlined_images rewrites inlined images:
+ <ul>
+ <li>If the image's data URL has not appeared earlier in the page then,
+ if it doesn't already have one an <code>id</code> attribute is
+ generated and added to the tag, then the existing/added <code>id</code>
+ is recorded along with the data URL for comparison with subsequent
+ inlined images.</li>
+ <li>Otherwise, the <code><img></code> tag is replaced with an
+ inline <code><script></code> tag that replaces itself with an
+ <code><img></code> tag, loading the data URL from the preceding
+ <code><img></code> tag with the <code>id</code> matching this
+ tag's data URL.</li>
+ </ul>
+</p>
+
+<h3>Example</h3>
+<p>
+ The effect of this filter can be observed on modpagespeed.com
+ <a href="https://www.modpagespeed.com/examples/dedup_inlined_images.html?ModPagespeed=off">before</a>
+ and
+ <a href="https://www.modpagespeed.com/examples/dedup_inlined_images.html?ModPagespeed=on&ModPagespeedFilters=inline_images,dedup_inlined_images">after</a>
+ rewriting.
+</p>
+
+<h2>Requirements</h2>
+<p>
+ The <a href="filter-image-optimize#inline_images">inline_images</a>
+ filter should be enabled for this filter to have any effect although it
... 14512 lines suppressed ...