From d9b15ba4e6f4801ce22b286e518d972e118c0760 Mon Sep 17 00:00:00 2001 From: Hallo5000 Date: Fri, 23 Jan 2026 02:43:53 +0100 Subject: [PATCH 1/3] added an explanation on how to automatically update a projects Resource Page --- src/content/docs/misc/hangar-publishing.md | 94 ++++++++++++++-------- 1 file changed, 60 insertions(+), 34 deletions(-) diff --git a/src/content/docs/misc/hangar-publishing.md b/src/content/docs/misc/hangar-publishing.md index ad66c43f5..5d4537d85 100644 --- a/src/content/docs/misc/hangar-publishing.md +++ b/src/content/docs/misc/hangar-publishing.md @@ -4,7 +4,7 @@ description: How to automatically publish your plugin to Hangar on commits. slug: misc/hangar-publishing --- -If you want to automatically publish your plugin to [Hangar](https://hangar.papermc.io/) on commits, you can use +If you want to automatically publish your plugin to [Hangar](https://hangar.papermc.io/) on pushes, you can use our [Gradle plugin](https://github.com/HangarMC/hangar-publish-plugin). After you have added the required `hangarPublish` configuration, you can manually publish it by @@ -133,7 +133,45 @@ hangarPublish { } ``` -### Optional: Going deeper +### GitHub Actions workflow + +You don't necessarily need to publish via GitHub Actions, but it is an easy way to do so. If you want to use it, create +a `publish.yml` file in the `.github/workflows` directory of your project root folder and make sure +you [add the repository secret](#adding-the-hangar_api_token-repository-secret). + +You can add and remove branches to be published by editing the `branches` section. + +```yaml +name: Publish to Hangar +on: + push: + branches: + # Add any additional branches you want to automatically publish from + - main # Assuming your main branch is called 'main' + +jobs: + publish: + # TODO: Optional, make sure the task only runs on pushes to your repository and doesn't fail on forks. Uncomment the line below and put the repo owner into the quotes + # if: github.repository_owner == '' + runs-on: ubuntu-22.04 + steps: + - name: Checkout Repository + uses: actions/checkout@v3 + - name: Validate Gradle Wrapper + uses: gradle/wrapper-validation-action@v1 + - name: Set up JDK 17 + uses: actions/setup-java@v3 + with: + distribution: 'temurin' + java-version: 17 + - name: Publish + env: + # Make sure you have added a repository secret in the repository's settings + HANGAR_API_TOKEN: ${{ secrets.HANGAR_API_TOKEN }} + run: ./gradlew build publishPluginPublicationToHangar --stacktrace +``` + +### Optional: Handling multiple channels and an automatic changelog With the following channels, any version that contains a hyphen (`-`) will be published under the `Snapshot` channel that you need to create on Hangar. By editing the `channel.set(...)` line, you can change this to any channel you would @@ -188,40 +226,28 @@ hangarPublish { } ``` -### GitHub Actions workflow +### Optional: Updating the Resource Page -You don't necessarily need to publish via GitHub Actions, but it is an easy way to do so. If you want to use it, create -a `publish.yml` file in the `.github/workflows` directory of your project root folder and make sure -you [add the repository secret](#adding-the-hangar_api_token-repository-secret). +At one point you might want to completely automate the process of publishing to HangarMC. One major part in this would be to update the 'Resource Page' (eg. the plugins home page). -You can add and remove branches to be published by editing the `branches` section. +There are two changes you need to make: -```yaml -name: Publish to Hangar -on: - push: - branches: - # Add any additional branches you want to automatically publish from - - main # Assuming your main branch is called 'main' +First you want to get the content for updating the Resource Page. In most cases this would likely be the `README.md` of your project. (of course you can use every file in your project by simply replacing `README.md` in the following code snippet with a path relative to your prjects root) -jobs: - publish: - # TODO: Optional, make sure the task only runs on pushes to your repository and doesn't fail on forks. Uncomment the line below and put the repo owner into the quotes - # if: github.repository_owner == '' - runs-on: ubuntu-22.04 - steps: - - name: Checkout Repository - uses: actions/checkout@v3 - - name: Validate Gradle Wrapper - uses: gradle/wrapper-validation-action@v1 - - name: Set up JDK 17 - uses: actions/setup-java@v3 - with: - distribution: 'temurin' - java-version: 17 - - name: Publish - env: - # Make sure you have added a repository secret in the repository's settings - HANGAR_API_TOKEN: ${{ secrets.HANGAR_API_TOKEN }} - run: ./gradlew build publishPluginPublicationToHangar --stacktrace +`val pageContent: String = project.file("README.md").readText(Charsets.UTF_8)` + +Registering the content to your projects Resource Page as follows completes the gradle part. +```kotlin +hangarPublish { + publications.register("plugin") { + pages.resourcePage(pageContent) + } +} +``` +Next we need to add the `syncAllPagesToHangar` task to the `Publish` step in your workflow: +```yaml +- name: Publish + env: + HANGAR_API_TOKEN: ${{ secrets.HANGAR_API_TOKEN }} + run: ./gradlew build publishPluginPublicationToHangar syncAllPagesToHangar --stacktrace ``` From 88066b4fea0b01e3e22a34809b9466b64b7b4760 Mon Sep 17 00:00:00 2001 From: Hallo5000 Date: Fri, 23 Jan 2026 14:16:00 +0100 Subject: [PATCH 2/3] minor spelling mistake --- src/content/docs/misc/hangar-publishing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/misc/hangar-publishing.md b/src/content/docs/misc/hangar-publishing.md index 5d4537d85..4a9acfa76 100644 --- a/src/content/docs/misc/hangar-publishing.md +++ b/src/content/docs/misc/hangar-publishing.md @@ -232,7 +232,7 @@ At one point you might want to completely automate the process of publishing to There are two changes you need to make: -First you want to get the content for updating the Resource Page. In most cases this would likely be the `README.md` of your project. (of course you can use every file in your project by simply replacing `README.md` in the following code snippet with a path relative to your prjects root) +First you want to get the content for updating the Resource Page. In most cases this would likely be the `README.md` of your project. (of course you can use every file in your project by simply replacing `README.md` in the following code snippet with a path relative to your projects root) `val pageContent: String = project.file("README.md").readText(Charsets.UTF_8)` From 44102c50f6212c553d76385bf4d92a0c5220823d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Ku=C4=8Dera?= Date: Sat, 21 Feb 2026 22:07:49 +0100 Subject: [PATCH 3/3] refactor: cleanup --- src/content/docs/misc/hangar-publishing.md | 36 ++++++++++++---------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/src/content/docs/misc/hangar-publishing.md b/src/content/docs/misc/hangar-publishing.md index 4a9acfa76..f73fa4042 100644 --- a/src/content/docs/misc/hangar-publishing.md +++ b/src/content/docs/misc/hangar-publishing.md @@ -133,7 +133,7 @@ hangarPublish { } ``` -### GitHub Actions workflow +## GitHub Actions workflow You don't necessarily need to publish via GitHub Actions, but it is an easy way to do so. If you want to use it, create a `publish.yml` file in the `.github/workflows` directory of your project root folder and make sure @@ -171,11 +171,12 @@ jobs: run: ./gradlew build publishPluginPublicationToHangar --stacktrace ``` -### Optional: Handling multiple channels and an automatic changelog +## Optional: Handling multiple channels and an automatic changelog -With the following channels, any version that contains a hyphen (`-`) will be published under the `Snapshot` channel -that you need to create on Hangar. By editing the `channel.set(...)` line, you can change this to any channel you would -like. For example, you could further split builds depending on the branch you are currently on into `Alpha` builds. +With the following code, any version that contains a hyphen (`-`) will be published under the `Snapshot` channel +(that you need to create on Hangar) and the others on the `Release` channel. +By editing the `channel.set(...)` line, you can change this to any channel you would like. +For example, you could further split builds depending on the branch you are currently on into `Alpha` builds. :::caution @@ -226,28 +227,29 @@ hangarPublish { } ``` -### Optional: Updating the Resource Page +## Optional: Updating the resource page -At one point you might want to completely automate the process of publishing to HangarMC. One major part in this would be to update the 'Resource Page' (eg. the plugins home page). +A notable part of publishing a new version might be updating the resource page (e.g. the plugin's home page) with new content from your plugin's repository. -There are two changes you need to make: +In this example, we're using a README file, but you can use any text you want, as long as it is in Markdown format. -First you want to get the content for updating the Resource Page. In most cases this would likely be the `README.md` of your project. (of course you can use every file in your project by simply replacing `README.md` in the following code snippet with a path relative to your projects root) - -`val pageContent: String = project.file("README.md").readText(Charsets.UTF_8)` - -Registering the content to your projects Resource Page as follows completes the gradle part. ```kotlin +val pageContent = project.file("README.md").readText() + hangarPublish { publications.register("plugin") { + // ... (see above) pages.resourcePage(pageContent) } } ``` -Next we need to add the `syncAllPagesToHangar` task to the `Publish` step in your workflow: + +You can invoke the `syncPluginPublicationMainResourcePagePageToHangar` task to update the resource page on Hangar. +This will not publish a new version, but simply update the page content on Hangar. + +If you're using a GitHub Actions workflow, you should also add the task invocation to the `Publish` step in your workflow: ```yaml - name: Publish - env: - HANGAR_API_TOKEN: ${{ secrets.HANGAR_API_TOKEN }} - run: ./gradlew build publishPluginPublicationToHangar syncAllPagesToHangar --stacktrace + # ... + run: ./gradlew build publishPluginPublicationToHangar syncPluginPublicationMainResourcePagePageToHangar --stacktrace ```