Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update sample work flow file in UG #2556

Merged
merged 7 commits into from
Jul 2, 2024
Merged

Update sample work flow file in UG #2556

Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bef0024
Add minute documentation changes
gerteck Jun 11, 2024
448d3f1
Update docs
gerteck Jun 13, 2024
97b4f90
Add info box
gerteck Jun 14, 2024
a72e93e
Reposition info box
gerteck Jun 16, 2024
0ef8751
Undo list autoformat
gerteck Jun 19, 2024
841d084
Add info
gerteck Jun 21, 2024
fa1c801
Reposition enable github pages
gerteck Jun 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion docs/userGuide/deployingTheSite.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,11 @@

**MarkBind can easily deploy a site to [GitHub pages](https://help.github.com/categories/github-pages-basics/)** if the project root directory is also a GitHub repo.

<box type="info">

This documentation currently uses `master` as the default branch name. If your repository uses `main` as the default branch, you will need to update the references to `master` accordingly. For instance, when specifying the branch for deployment, replace instances of `master` with `main` to match your repository's configuration.
</box>

### Using the `markbind deploy` command

Running the **`markbind deploy`** command will deploy the most recent build of your site to the `gh-pages` branch of the repo `origin` and will be available.
Expand Down Expand Up @@ -102,6 +107,8 @@ jobs:
build:
runs-on: ubuntu-latest
name: test
permissions:
contents: write
env:
GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
steps:
Expand All @@ -118,7 +125,13 @@ jobs:
The sample `deploy.yml` workflow above uses the [default GitHub Token secret](https://docs.github.com/en/actions/reference/authentication-in-a-workflow) that is generated automatically for each GitHub Actions workflow. You may also use a [GitHub Personal Access Token](#generating-a-github-personal-access-token) in place of the default GitHub Token.
</box>

Once you have created the file, commit and push the file to your repo. GitHub Actions should start to build and deploy your MarkBind site. You can verify this by visiting `www.github.com/<org|username>/<repo>/actions`.
Once you have created the file, commit and push the file to your repo.

For the first deployment on GitHub Pages, you will need to manually configure and enable GitHub Pages.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this duplicated info from line 50 above?
image

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, I also realised that it was previously mentioned aboved to manually enable github pages under markbind deploy. From my MarkBind set up experience, manually enabling GitHub Pages was only necessary for setting up GitHub Actions, but not required when using the command markbind deploy.

Would it be better to instead add a reminder e.g. If deploying on GitHub Pages for the first time, enable GitHub Pages as per under markbind deploy, or completely do away with this mention?

I am unsure if this addition would be entirely relevant, as in my setup process, I jumped directly to setting up GitHub Actions instead of first using the markbind deploy command, which may not be the default expected workflow. I agree that if they ran markbind deploy, or took note of the above steps, adding this info would be unneccesary.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From my MarkBind set up experience, manually enabling GitHub Pages was only necessary for setting up GitHub Actions, but not required when using the command markbind deploy.

Yup you are right. I probably had the wrong impression that it needs to be done even for markbind deploy command.

We can move this part from markbind deploy:
image

to somewhere here under "Deploying via GitHub Actions"
image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, to clarify, when you mention GitHub Actions, do you mean via the following:

name: Deploy MarkBind Site
on:
  push:
    branches: master

jobs:
  build:
    runs-on: ubuntu-latest
    name: test
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '16'
      - run: npm i -g markbind-cli
      - run: markbind deploy --ci

or using markbind-action ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeap! sounds good, thank you!

I was referring to the former:

name: Deploy MarkBind Site
on:
  push:
    branches: master

jobs:
  build:
    runs-on: ubuntu-latest
    name: test
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '16'
      - run: npm i -g markbind-cli
      - run: markbind deploy --ci

* Navigate to the `Settings > Pages` section on GitHub for your repository.
* Select `Deploy from a branch` in the `Source` dropdown, and set the source branch to the root of the `gh-pages` branch.

GitHub Actions should start to build and deploy your MarkBind site. You can verify this by visiting `www.github.com/<org|username>/<repo>/actions`.

<box type="tip" id="markbind-action-tip">

Expand Down
Loading