From 95ad18ea8038a012f8af3c542d787b044067354b Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 19 Jan 2022 11:45:51 +0100 Subject: [PATCH] Update instructions for GH Pages --- README.md | 16 +++++++++++----- docs/modules/ROOT/nav.adoc | 2 +- docs/modules/ROOT/pages/explanations/.gitkeep | 0 3 files changed, 12 insertions(+), 6 deletions(-) create mode 100644 docs/modules/ROOT/pages/explanations/.gitkeep diff --git a/README.md b/README.md index decf54b..2dfaeaf 100644 --- a/README.md +++ b/README.md @@ -73,10 +73,11 @@ After completing a task, you can remove the comment in the files. - "Options > Wiki" (disable) - "Options > Allow auto-merge" (enable) - "Options > Automatically delete head branches" (enable) - - "Branches > Default branch" (change to `master`) (VSHN's default) + - "Collaborators & Teams > Add Teams and users to grant maintainer permissions - "Branches > Branch protection rules": - Branch name pattern: `master` - Require status check to pass before merging: `["lint"]` (you may need to push come commits first) + - "Pages > Source": Branch `gh-pages` 1. GitHub Issue labels - "Issues > Labels > New Label" for the following labels with color suggestions: @@ -95,8 +96,12 @@ By default, it is automatically published to GitHub Pages in `gh-pages` branch, ### Setup GitHub Pages -Let's prepare and empty `gh-pages` branch, but make sure to **commit or stash current changes first!** +Once you generated a new repository using this template, the initial commit automatically runs a Job that creates the documentation in the `gh-pages` branch. +All you need to do is then to enable Pages in the settings. +The `gh-pages` branch is a parent-less commit that only contains the Antora-generated files. + +However, if that's not the case or if you are setting up Antora in an existing repository, here's how you can achieve the same, but make sure to **commit or stash current changes first!** ```bash current_branch=$(git rev-parse --abbrev-ref HEAD) initial_commit=$(git rev-list --max-parents=0 HEAD) @@ -108,13 +113,14 @@ git switch -f $current_branch ``` And you're done! -GitHub automatically recognizes and sets up Pages if there's a `gh-pages` branch. +GitHub automatically recognizes activity and sets up Pages if there's a `gh-pages` branch. --- If you want to skip deployment to GitHub Pages you need to delete specific files and references: -`rm -f .github/workflows/docs.yml docs/package*.json docs/antora-playbook.yml docs/antora-build.mk` +`rm -f .github/workflows/docs.yml docs/package*.json docs/antora-playbook.yml docs/antora-build.mk`. +Also don't forget to delete the branch and disable Pages in the repository settings. --- -If you want to remove documentation completely simply run `rm -rf docs .github/workflows/docs.yml` +If you want to remove documentation completely simply run `rm -rf docs .github/workflows/docs.yml`. diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 8801dc8..ee477ec 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -11,5 +11,5 @@ .Technical reference //* xref:references/example.adoc[Example Reference] -//.Explanation +.Explanation //* xref:explanations/example.adoc[Example Explanation] diff --git a/docs/modules/ROOT/pages/explanations/.gitkeep b/docs/modules/ROOT/pages/explanations/.gitkeep new file mode 100644 index 0000000..e69de29