Pages documentation section migration

_data/pages/navigation.yaml

@@ -102,7 +102,7 @@ sidenav:
       - text: Specific build errors
         href: /pages/documentation/build-errors/
       - text: Environment variables on builds
-        href: /pages/documentation/env-vars-on-content-builds/
+        href: /pages/documentation/env-vars-on-pages-builds/
       - text: Pages and cloud.gov
         href: /pages/documentation/cloud-gov/
       - text: Node on Pages

_includes/layouts/docs.html

@@ -10,7 +10,11 @@
     <div class="grid-container">
         <div class="grid-row grid-gap">
             {% if sidenav == true %}
-            {% include "sidenav.html" %}
+                {% if navigation == "pages" %}
+                    {% include "pages/sidenav.html" %}
+                {% else %}
+                    {% include "sidenav.html" %}
+                {% endif %}
             {% endif %}
             <main id="main-content"
                   class="usa-layout-docs__main usa-prose bg-white padding-y-8 padding-x-4 desktop:grid-col-8">
@@ -19,7 +23,7 @@ <h1>{{ title }}</h1>
                 {% assign toc_content = content | toc | strip | strip_newlines %}
                 {% assign empty_toc_content = '<ol id="toc" class="section-nav"></ol>' %}
 
-                {% if toc_content != '' and toc_content != empty_toc_content %}
+                {% if showtoc != false and toc_content != '' and toc_content != empty_toc_content %}
                 <h2>Table of Contents</h2>
                 <div id="table-of-contents">
                     {{ toc_content }}

_includes/pages/components/alert--best-practice.html

@@ -1 +1 @@
-{% include pages/components/alert.html heading="Best practice" status="success" content=include.content html=include.html %}
+{% include "pages/components/alert.html" heading: "Best practice" status: "success" content: content html: "include.html" %}

_includes/pages/components/alert--note.html

@@ -1 +1 @@
-{% include pages/components/alert.html heading="Note" status="warning" content=include.content html=include.html %}
+{% include "pages/components/alert.html" heading: "Note" status: "warning" content: content html: "include.html" %}

_includes/pages/components/alert--tip.html

@@ -1 +1 @@
-{% include pages/components/alert.html heading="Tip" status="info" content=include.content html=include.html %}
+{% include "pages/components/alert.html" heading: "Tip" status: "info" content: include.content html: "include.html" %}

_includes/pages/components/alert.html

@@ -4,12 +4,12 @@
 {% endcomment %}
 <div class="usa-alert usa-alert--{{ include.status | default: 'info' }}">
   <div class="usa-alert__body">
-    <h3 class="usa-alert__heading">{{ include.heading | escape }}</h3>
+    <h3 class="usa-alert__heading">{{ heading | escape }}</h3>
     <div class="usa-alert__text">
-      {% unless include.html %}
-        {{ include.content | strip | markdownify }}
+      {% unless "include.html" %}
+        {{ content | strip | markdown }}
       {% else %}
-        {{ include.content }}
+        {{ content }}
       {% endunless %}
     </div>
   </div>

_includes/pages/components/glossary.html

@@ -1,6 +1,6 @@
 <div id="glossary" class="glossary" aria-describedby="glossary-title" aria-hidden="true">
   <button title="close glossary" class="js-glossary-close close">
-    <img src="{{ site.baseurl }}/assets/images/pages/close.svg" alt="Hide glossary">
+    <img src="{{ '/img/pages/close.svg' | url }}" alt="Hide glossary">
   </button>
   <h3>Glossary</h3>
   <label for="glossary-search">Filter glossary terms</label>

_includes/sidenav.html

@@ -2,7 +2,6 @@
 The sidenav is not loaded by default on the main pages. To include this navigation you can either use the
 _layouts/page.html layout template, or you can add "sidenav: true" in the front-matter of your pages
 {%- endcomment -%}
-
 <aside id="section-nav" class="usa-layout-docs-sidenav desktop:grid-col-4 padding-bottom-4">
   <nav>
     <ul class="usa-sidenav">

content/pages/documentation/21st-century-idea.md

@@ -0,0 +1,28 @@
+---
+title: 21st Century IDEA
+permalink: /pages/documentation/21st-century-idea/
+
+
+---
+
+
+The <b>21st Century Integrated Digital Experience Act (IDEA)</b> aims to improve the digital experience for government customers and reinforces existing requirements for federal public websites. Specifically, the Act requires all executive branch agencies to:
+
+- modernize their websites,
+- digitize services and forms,
+- accelerate use of e-signatures,
+- improve customer experience, and
+- standardize and transition to centralized shared services.
+
+All new, public-facing websites and digital services must meet eight specific requirements:
+
+1. **Accessible** - be accessible to individuals with disabilities in accordance with Section 508
+2. **Consistent** - have a consistent appearance
+3. **Authoritative** - not overlap with or duplicate existing websites
+4. **Searchable** - contain a search function
+5. **Secure** - be provided through a secure connection
+6. **User-centered** - be designed around user needs with data-driven analysis
+7. **Customizable** - provide an option for a more customized digital experience
+8. **Mobile-friendly** - be functional and usable on mobile devices
+
+To learn more about this law, check out the [21st Century IDEA resource on Digital.gov](https://digital.gov/resources/21st-century-integrated-digital-experience-act/).

content/pages/documentation/Pages-security-compliance.md

@@ -0,0 +1,78 @@
+---
+title: Pages Security and Compliance
+permalink: /pages/documentation/security-and-compliance/
+
+
+---
+
+## Pages security and compliance documentation
+
+The Federalist Authority to Operate (ATO) expired on February 28, 2024.
+All Federalist sites, including non-GSA websites, have transitioned from the Federalist ATO to the cloud.gov Pages security boundary.
+Sites will remain active under an agreement while the site owner compiles the Authority to Use (ATU) documentation.
+
+## What is an Authority to Use (ATU)?
+
+An ATU defines the process for documenting, reviewing, and approving the security and compliance status of sites requesting onboarding to the cloud.gov Pages platform.
+The ATU package is a consolidated document containing detailed security and compliance information for government low-impact information resources.
+
+## Cloud.gov Pages ATU
+
+The Pages team has created an ATU process and established a partnership with the Technology Transformation Services Center of Excellence (CoE) to assist non-GSA agencies in navigating and gathering ATU documentation. **The process includes the following templates and documents which are available upon request via this email: [Pages Support](mailto:pages-support@cloud.gov).**
+
+- Templates
+  - Authority to Use main template
+  - Privacy Threshold Analysis (PTA)
+  - Contingency Plan (CP)
+  - Configuration Management Plan (CMP)
+  - Incident Response Plan (IRP)
+  - Control guide for non-GSA websites
+  - Authority to Use letter **[This is a SAMPLE ONLY]**
+- ATU checklist
+- Pages CIS/CRM
+- Agency-specific requirements
+- ATU process flow
+
+## Benefits of using the Pages ATU package
+
+By leveraging cloud.gov Pages, government agencies benefit from a highly secure and compliant website hosting solution. The platform's adherence to federal security standards and its robust security features, high availability, centralized security management, and support from security experts and engineers make it an ideal choice for hosting government websites.
+The cloud.gov Pages ATU provides:
+
+- Streamlined compliance: Simplifies the compliance process for non-GSA agencies.
+- Consolidated documentation: Provides all necessary security and compliance details in one place.
+- Expert assistance: Partnership with CoE ensures expert guidance throughout the ATU process.
+- Ongoing support: Continuous support from the cloud.gov Pages team to maintain compliance.
+
+This focus on security and compliance helps agencies protect their data, meet regulatory requirements, and ensure the integrity and availability of their digital services.
+
+## ATU process flow
+
+The ATU process flow is determined by if you would like guided ATU support or would like to self-complete the ATU process.
+
+The process is outlined below. Here is where you can see a chart illustrating the process: [Authority to Use - Process Flow.pptx](https://github.com/user-attachments/files/16364072/Authority.to.Use.-.Process.Flow.pptx)
+
+Both the guided ATU support process and the ATU self-completion process begin with initiating a request for service to the Cloud.gov Pages team.
+
+## Guided ATU support process
+
+If you opt for guided ATU support, your request will be directed to the Centers of Excellence (CoE). The CoE will review the initial request and consult the Pages team to ensure the request aligns with ATU requirements.
+
+Once ATU requirement alignment has been determined, you will complete the required documentation under CoE guidance. Cg-Pages DevOps will engage with you to onboard you to the Pages application. The CoE team, along with cg-Pages Compliance, will conduct a final review of your documentation.
+
+If the documentation meets your agency’s requirements (agency ISSO/ISSM or FedRAMP), the site owner will sign the ATU document and ATU letter ISSO/ISSM and move the ATU letter forward to obtain the rest of the signature requests.
+
+Prior to operational deployment, all websites must receive written authorization through the ATU process.
+
+Once written authorization is received, the Cg-Pages DevOps team will collaborate with you to deploy the live site.
+
+## ATU self-completion process
+
+If you are opting to self-complete the ATU process, you may leverage either the non-GSA ATU process (without the assistance of the CoE team, as outlined above) or follow your agency-specific ATO/ATU process.
+
+Prior to operational deployment, all websites must receive written authorization through the ATU process.
+
+## Cloud.gov Pages contact information
+
+Need help with an existing Pages account? Contact the support team at pages-support@cloud.gov.
+
+Interested in getting started with Pages? Contact the business team at inquiries@cloud.gov.

content/pages/documentation/add-user.md

@@ -0,0 +1,44 @@
+---
+title: Adding users to Organizations
+permalink: /pages/documentation/adding-users/
+
+
+---
+
+
+## User Requirements
+
+As a new user, reach out to your organization’s manager to be invited to the platform and subsequently the desired organization. 
+
+If you are having trouble locating who the organization manager is you can reach out in one of our slack channels #cg-pages or #cg-pages-public.
+
+## Adding a new user
+
+- Navigate to the organizations tab
+- Click edit in the lower right hand corner of the organization pane
+  <img src="{{ '/img/pages/edit_organizations.png' | url }}"/>
+
+- Click the plus sign under “Members” 
+  <img src="{{ '/img/pages/add_user.png' | url }}"/>
+
+- Fill out the required fields of Email and Role
+ * If you do not know the GitHub username of the invitee you can add it post invite
+
+- Click Invite
+
+## User Acceptance
+
+As a new user to the platform you will be sent an invitation via email. The link in the email will take you directly to the cloud.gov login page to authenticate your credentials.  You will need to create a cloud.gov account and then use these credentials to login to Pages. 
+
+\*Note if a user already belongs to these agencies FDIC, EPA, NIH, GSA, DOJ, OMB or has existing cloud.gov credentials they can use their existing account login information to authenticate into Pages.
+
+
+
+Decap CMS users **must** login to pages.cloud.gov prior to using the content editor.
+
+## Who should be added
+
+* New project team members
+* Contractors
+* Anyone who needs to view the organization's build logs
+

content/pages/documentation/automated-site-reports.md

@@ -0,0 +1,65 @@
+---
+title: Automated Site Reports
+permalink: /pages/documentation/automated-site-reports/
+
+
+redirect_from:
+  - /pages/documentation/build-scans/
+---
+
+
+Automated Site Reports are a new feature being offered by Pages.
+
+Users can generate scheduled or on-demand reports which check their website for security vulnerabilities, accessibility violations, and other relevant information to help improve their site. These reports are generated monthly or can be requested manually from the build history page. There are currently two reports available: ZAP Security Report and WCAG Accessibility Report.
+
+## ZAP Security Report
+
+The ZAP Security Report tests your published website for common security vulnerabilities. It uses the [Zed Attack Proxy (ZAP)](https://www.zaproxy.org/) software to passively scan the site for vulnerabilities but does not perform any attack or attempt to maliciously modify your site code. Example security findings include unintended exposure of sensitive data, SQL injection opportunities, cross-site scripting (XSS) flaws, and the use of components with known vulnerabilities. More details about the mechanisms used to generate this report and the resulting file output can be found at [ZAP -  Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/)
+
+## WCAG Accessibility Report
+
+This report identifies website accessibility violations from [Section 508](https://www.section508.gov/) and the [latest WCAG version](https://www.w3.org/TR/WCAG22/). The report is generated by first crawling your website to identify all pages to test. It then uses the open source portion of [`axe`](https://www.deque.com/axe/) to identify accessibility violations. The final report is a custom documented generated from the `axe` output. Note that for sites without a page at the root of their domain, this report will fail because the site crawler will not find any pages.
+
+### Configuration
+
+Automated Site Reports will automatically suppress certain findings which are irrelevant for statically hosted websites, based on unconfigurable server settings, or frequently produce ‘false positive’ findings for our customers.
+
+#### False Positives
+
+The following rules are suppressed because they are triggered by false findings: `Source Code Disclosure`, `Hash Disclosure - MD4 / MD5` (in the `/assets/styles` folder only)
+
+#### Unconfigurable Server Settings
+
+The following rules are suppressed because they are not able to be configured by the end user: `Content Security Policy (CSP) Header Not Set`, `Permissions Policy Header Not Set`, `Cross-Domain Misconfiguration`, `Insufficient Site Isolation Against Spectre Vulnerability`
+
+#### Other Exclusions
+
+The following rules are suppressed because they demonstrate correct use of TTS properties ([Digital Analytics Program](https://digital.gov/guides/dap/) and [Search.gov](https://search.gov/)) which nonetheless trigger security findings: `Cross-Domain JavaScript Source File Inclusion`, `Absence of Anti-CSRF Tokens`, `Sub Resource Integrity Attribute Missing`.
+
+Details for certain suppressed findings are below:
+
+#### Content Security Policy (CSP) Header Not Set
+
+Pages sets headers for all sites with a single proxy application. Because headers cannot be managed per-site, this header is not set. To achieve nearly identical Content Security Policy (CSP) protection, site developers can add [`meta` tags to each page describing the CSP rules](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
+
+[ZAP link](https://www.zaproxy.org/docs/alerts/10038/)
+
+#### Cross-Domain JavaScript Source File Inclusion
+
+Inclusion of the Digital Analytics Program and Search.gov JavaScript files is the recommend pattern for using both services:
+- [Get started with DAP](https://digital.gov/guides/dap/get-started-with-dap/#step-2-add-the-dap-code-to-your-website-to-collect-data)
+- [Setting up Search.gov for Cloud.gov Pages sites](https://search.gov/get-started/searchgov-for-cloudgov-pages.html)
+
+[ZAP link](https://www.zaproxy.org/docs/alerts/10017)
+
+#### Absence of Anti-CSRF Tokens
+
+The Search.gov search form does not perform actual HTML form submission and thus does not require a CSRF token.
+
+[ZAP link](https://www.zaproxy.org/docs/alerts/10202)
+
+#### Sub Resource Integrity Attribute Missing
+
+The Digital Analytics Program does not currently publish scripts with a Sub Resource Integrity Attribute
+
+[ZAP link](https://www.zaproxy.org/docs/alerts/90003)

content/pages/documentation/before-you-launch.md

@@ -0,0 +1,41 @@
+---
+title: Before you launch
+permalink: /pages/documentation/before-you-launch/
+
+
+---
+
+We've worked to make publishing a government site on Pages as simple as possible. Please note that while the entire process usually takes a couple days, it may take up to a week, so plan accordingly.
+
+- [Requirements](#requirements)
+- [Launch Process](#launch-process)
+- [Launch Checklist](#launch-checklist)
+
+## Requirements
+- You must have an active, signed IAA with Pages. Sandbox accounts without IAAs will be unable to configure custom domains and preview urls are **not** suitable for production use.
+
+- Your agency must accept the risk of launching a site on Pages. Be sure to follow your agency's procedures and guidelines for operating your site using Pages.
+
+- You must understand [your responsibilities]({{ site.baseurl }}{{ '/pages/documentation/customer-responsibilities' | url }}).
+
+- Ensure you know how, or who to contact to make changes to the DNS configuration for your domain.
+
+- If necessary, obtain a custom domain.
+
+## Launch Process
+1. Notify Pages support of your intent to launch along with your repository name/url and production-ready git branch via:
+- email: `pages-support@cloud.gov`
+- Slack: `#cg-pages`
+
+2. Complete any site security scanning requirements as required by your agency CISO. Read our [documentation about required security scanning]({{site.baseurl}}/pages/documentation/external-tools-and-resources/#scanning-tools) for more information
+
+3. Complete the process of [adding your custom domain]({{ site.baseurl }}{{ '/pages/documentation/custom-domains' | url }}). If you are migrating an existing site to Pages, make sure to review [minimizing downtime]({{ site.baseurl }}{{ '/pages/documentation/custom-domains' | url }}#minimizing-downtime)
+
+4. Your site will now be live!
+
+## Launch Checklist
+
+1. Notify Pages support that you are ready to launch your site
+2. [Configure your DNS]({{ site.baseurl }}{{ '/pages/documentation/custom-domains' | url }}#configure-your-dns)
+3. Notify Pages support
+4. [Configure your custom domain]({{ site.baseurl }}{{ '/pages/documentation/custom-domains' | url }}#configure-your-custom-domain))

content/pages/documentation/build-errors.md

@@ -0,0 +1,12 @@
+---
+title: Build Errors
+permalink: /pages/documentation/build-errors/
+
+
+---
+
+
+The following is a non-exhausitve list of commmon issues we see partners run into:
+
+- Trying to deploy code that uses the `github-pages` gem interferes with the Pages build process to specific URLs. Users should always remove that gem from their repos.
+- Errors like "Pages can't confirm org permissions for 'your-org'." Either `your-org` hasn't approved access for Pages or you aren't an org member. Ensure you are an org member and ask an org owner to authorize Pages for the organization can be resolved by visiting [this link](https://github.com/settings/connections/applications/94d4097d74049df1039b) and requesting org access as needed. This happens because Pages can't tap a repo without org approval. Typically these permissions are granted when initially granting access to Pages.

content/pages/documentation/bundler-on-pages.md

@@ -0,0 +1,15 @@
+---
+title: Bundler on Pages
+permalink: /pages/documentation/bundler-on-pages/
+
+
+---
+
+
+Pages uses [Bundler](https://bundler.io/) to manage your Pages site's dependencies.  By default, Pages runs Bundler version 1.
+
+## Specifying a Bundler version
+
+Prior to building a site, the build will check for a file named `.bundler-version`. If one is found, it will use the Bundler version specified to install the gems and versions declared for you site.
+
+For example, if you wish to use Bundler version 2.0.1 to build a site, add a new file named `.bundler-version` to your repository. The `.bundler-version` file should be at the top-level directory. The contents of that file should be "`2.0.1`".