[2023-02-22]: Disable symlinks on legacy pages build infrastructure - [GA] (github#34673)

Co-authored-by: Siara <[email protected]>

Author: sophietheking

content/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site.md

@@ -31,27 +31,39 @@ shortTitle: Configure publishing source
 {% data reusables.pages.sidebar-pages %}
 {% ifversion pages-custom-workflow %}
 1. Under "Build and deployment", under "Source", select **Deploy from a branch**.
-1. Under "Build and deployment", under "Branch", use the **None** or **Branch** drop-down menu and select a publishing source.
+1. Under "Build and deployment", under "Branch", use the **None** or **Branch** dropdown menu and select a publishing source.
+
+   ![Screenshot of the dropdown menu to select a publishing source](/assets/images/help/pages/publishing-source-drop-down.png)
 
-   ![Drop-down menu to select a publishing source](/assets/images/help/pages/publishing-source-drop-down.png)
 {% else %}
 3. Under "{% data variables.product.prodname_pages %}", use the **None** or **Branch** drop-down menu and select a publishing source.
-  ![Drop-down menu to select a publishing source](/assets/images/help/pages/publishing-source-drop-down.png)
+
+   ![Screenshot of the dropdown menu to select a publishing source](/assets/images/help/pages/publishing-source-drop-down.png)
+
 {% endif %}
-4. Optionally, use the drop-down menu to select a folder for your publishing source.
-  ![Drop-down menu to select a folder for publishing source](/assets/images/help/pages/publishing-source-folder-drop-down.png)
-5. Click **Save**.
-  ![Button to save changes to publishing source settings](/assets/images/help/pages/publishing-source-save.png)
+1. Optionally, use the drop-down menu to select a folder for your publishing source.
+
+   ![Screenshot of the dropdown menu to select a folder for publishing source](/assets/images/help/pages/publishing-source-folder-drop-down.png)
+
+1. Click **Save**.
+
+   ![Screenshot of the button to save changes to publishing source settings](/assets/images/help/pages/publishing-source-save.png)
 
 ### Troubleshooting publishing from a branch
 
+{% ifversion pages-disable-symlinks-on-legacy-pages %}
+
+{% data reusables.pages.symlink-removal %}
+
+{% endif %}
+
 {% data reusables.pages.admin-must-push %}
 
 If you choose the `docs` folder on any branch as your publishing source, then later remove the `/docs` folder from that branch in your repository, your site won't build and you'll get a page build error message for a missing `/docs` folder. For more information, see "[AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites#missing-docs-folder)."
 
 {% ifversion build-pages-with-actions %}
 
-Your {% data variables.product.prodname_pages %} site will always be deployed with a {% data variables.product.prodname_actions %} workflow run, even if you've configured your {% data variables.product.prodname_pages %} site to be built using a different CI tool. Most external CI workflows "deploy" to GitHub Pages by committing the build output to the `gh-pages` branch of the repository, and typically include a `.nojekyll` file. When this happens, the {% data variables.product.prodname_actions %} workflow will detect the state that the branch does not need a build step, and will execute only the steps necessary to deploy the site to {% data variables.product.prodname_pages %} servers.
+Your {% data variables.product.prodname_pages %} site will always be deployed with a {% data variables.product.prodname_actions %} workflow run, even if you've configured your {% data variables.product.prodname_pages %} site to be built using a different CI tool. Most external CI workflows "deploy" to {% data variables.product.prodname_pages %} by committing the build output to the `gh-pages` branch of the repository, and typically include a `.nojekyll` file. When this happens, the {% data variables.product.prodname_actions %} workflow will detect the state that the branch does not need a build step, and will execute only the steps necessary to deploy the site to {% data variables.product.prodname_pages %} servers.
 
 To find potential errors with either the build or deployment, you can check the workflow run for your {% data variables.product.prodname_pages %} site by reviewing your repository's workflow runs. For more information, see "[AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)." For more information about how to re-run the workflow in case of an error, see "[AUTOTITLE](/actions/managing-workflow-runs/re-running-workflows-and-jobs)."
 
@@ -68,7 +80,7 @@ To configure your site to publish with {% data variables.product.prodname_action
 {% data reusables.pages.navigate-site-repo %}
 {% data reusables.repositories.sidebar-settings %}
 {% data reusables.pages.sidebar-pages %}
-1. Under "Build and deployment", under "Source", select **GitHub Actions**.
+1. Under "Build and deployment", under "Source", select **{% data variables.product.prodname_actions %}**.
 1. {% data variables.product.product_name %} will suggest several starter workflows. If you already have a workflow to publish your site, you can skip this step. Otherwise, choose one of the options to create a {% data variables.product.prodname_actions %} workflow. For more information about creating your custom workflow, see "[Creating a custom {% data variables.product.prodname_actions %} workflow to publish your site](#creating-a-custom-github-actions-workflow-to-publish-your-site)."
 
    {% data variables.product.prodname_pages %} does not associate a specific workflow to the {% data variables.product.prodname_pages %} settings. However, the {% data variables.product.prodname_pages %} settings will link to the workflow run that most recently deployed your site.
@@ -90,6 +102,7 @@ The starter workflows use a deployment environment called `github-pages`. If you
 {% ifversion fpt or ghec %}
 {% note %}
 
+
 **Note**: A `CNAME` file in your repository file does not automatically add or remove a custom domain. Instead, you must configure the custom domain through your repository settings or through the API. For more information, see "[AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain)" and the [Pages API reference documentation](/rest/pages#update-information-about-a-github-pages-site).
 
 {% endnote %}

content/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites.md

@@ -60,6 +60,12 @@ To troubleshoot, make sure that your *_config.yml* file follows these rules:
 
 {% data reusables.pages.yaml-linter %}
 
+{% ifversion pages-disable-symlinks-on-legacy-pages %}
+
+{% data reusables.pages.symlink-removal %}
+
+{% endif %}
+
 ## Date is not a valid datetime
 
 This error means that one of the pages on your site includes an invalid datetime.
@@ -72,11 +78,13 @@ This error means that your code references a file that doesn't exist in your *_i
 
 {% data reusables.pages.search-for-includes %} If any of the files you've referenced aren't in the *_includes* directory, copy or move the files into the *_includes* directory.
 
+{% ifversion ghes < 3.9 %}
 ## File is a symlink
 
 This error means that your code references a symlinked file that does not exist in the published files for your site.
 
 {% data reusables.pages.search-for-includes %} If any of the files you've referenced are symlinked, copy or move the files into the *_includes* directory.
+{% endif %}
 
 ## File is not properly UTF-8 encoded
 
@@ -160,11 +168,13 @@ Permalinks are permanent URLs that reference a particular page on your site. Abs
 
 To troubleshoot, remove the `relative_permalinks` line from your *_config.yml* file and reformat any relative permalinks in your site with absolute permalinks. For more information, see "[AUTOTITLE](/repositories/working-with-files/managing-files/editing-files)."
 
+{% ifversion ghes < 3.9 %}
 ## Symlink does not exist within your site's repository
 
 This error means that your site includes a symbolic link (symlink) that does not exist in the published files for your site. For more information about symlinks, see "[Symbolic link](https://en.wikipedia.org/wiki/Symbolic_link)" on Wikipedia.
 
 To troubleshoot, determine if the file in the error message is used to build your site. If not, or if you don't want the file to be a symlink, delete the file. If the symlinked file is necessary to build your site, make sure the file or directory the symlink references is in the published files for your site. To include external assets, consider using {% ifversion fpt or ghec %}`git submodule` or {% endif %}a third-party package manager such as [Bower](https://bower.io/).{% ifversion fpt or ghec %} For more information, see "[AUTOTITLE](/pages/getting-started-with-github-pages/using-submodules-with-github-pages)."{% endif %}
+{% endif %}
 
 ## Syntax error in 'for' loop
 

data/features/pages-disable-symlinks-on-legacy-pages.yml

@@ -0,0 +1,6 @@
+# Issue 9540
+# Disable symlinks on legacy pages build infrastructure
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.9'

data/reusables/pages/admin-must-push.md

@@ -1,5 +1,5 @@
-{% tip %}
+{% note %}
 
 **Note**: {% ifversion pages-custom-workflow %}If you are publishing from a branch and{% else %}If{% endif %} your site has not published automatically, make sure someone with admin permissions and a verified email address has pushed to the publishing source.
 
-{% endtip %}
+{% endnote %}

data/reusables/pages/pages-custom-workflow-beta.md

@@ -2,7 +2,7 @@
 
 {% note %}
 
-Note: Publishing your {% data variables.product.prodname_pages %} site with a custom {% data variables.product.prodname_actions %} workflow is in beta and subject to change.
+**Note:** Publishing your {% data variables.product.prodname_pages %} site with a custom {% data variables.product.prodname_actions %} workflow is in beta and subject to change.
 
 {% endnote %}
 

data/reusables/pages/symlink-removal.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** If your repository contains symbolic links, you will need to publish your site using a {% data variables.product.prodname_actions %} workflow. For more information about {% data variables.product.prodname_actions %}, see "[Actions](/actions)."
+
+{% endnote %}