chore: add docs for --json usage

README.md

@@ -1,6 +1,5 @@
 <p align="center"><img src="https://github.com/user-attachments/assets/314d5112-f67f-4758-82bf-7b0c19c01ba6" /></p>
 
-
 # pkg.pr.new <span><img src="https://emoji.slack-edge.com/TFHDVN56F/stackblitz/fd010078dcccebca.png" width="30" /></span>
 
 > We call it "Continuous Releases" too.
@@ -27,7 +26,6 @@ It is aiming to reduce the number of these comments :)
 
 > This was fixed in #18. Can we release that fix?
 
-
 These are some of the projects and companies using pkg.pr.new:
 
 <p align="center">
@@ -149,6 +147,128 @@ And `--comment=off` would turn off comments for maintainers who prefer minimal p
 
 For repositories with many packages, comments might get too long. In that case, you can use `--only-templates` to only show templates.
 
+## Custom GitHub Messages and Comments
+
+For advanced use cases where you want more control over the messages posted by pkg.pr.new, you can use the `--json` option in combination with `--comment=off`. This allows you to generate metadata about the publish operation without creating a default comment, which you can then use to create custom comments via the GitHub Actions API.
+
+### Steps:
+
+1. Use pkg.pr.new with the `--json` and `--comment=off` options in your workflow:
+
+```yml
+name: Publish packages
+run: npx pkg-pr-new publish --json output.json --comment=off
+```
+
+2. Add a custom step in your workflow to process the JSON output and create a custom comment:
+
+```yml
+name: Post or update comment
+uses: actions/github-script@v6
+with:
+  github-token: ${{secrets.GITHUB_TOKEN}}
+  script: |
+    const fs = require('fs');
+    const output = JSON.parse(fs.readFileSync('output.json', 'utf8'));
+
+    const packages = output.packages.map(p => `- ${p.name}: ${p.url}`).join('\n');
+    const templates = output.templates.map(t => `- [${t.name}](${t.url})`).join('\n');
+    const body = `
+      ## Custom Publish Message for ${context.sha.substring(0, 7)}
+
+      ### Published Packages:
+      ${packages}
+
+      ### Templates:
+      ${templates}
+    `;
+
+    const botCommentIdentifier = '## Custom Publish Message';
+
+    async function findBotComment(issueNumber) {
+      if (!issueNumber) return null;
+
+      const comments = await github.rest.issues.listComments({
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        issue_number: issueNumber
+      });
+
+      return comments.data.find(comment => comment.body.includes(botCommentIdentifier));
+    }
+
+    async function createOrUpdateComment(issueNumber) {
+      if (!issueNumber) {
+        console.log('No issue number provided. Cannot post or update comment.');
+        return;
+      }
+
+      const existingComment = await findBotComment(issueNumber);
+
+      if (existingComment) {
+        await github.rest.issues.updateComment({
+          owner: context.repo.owner,
+          repo: context.repo.repo,
+          comment_id: existingComment.id,
+          body: body
+        });
+      } else {
+        await github.rest.issues.createComment({
+          issue_number: issueNumber,
+          owner: context.repo.owner,
+          repo: context.repo.repo,
+          body: body
+        });
+      }
+    }
+
+    function logPublishInfo() {
+      console.log('\n' + '='.repeat(50));
+      console.log('Publish Information for commit:', context.sha.substring(0, 7));
+      console.log('='.repeat(50));
+      console.log('\nPublished Packages:');
+      console.log(packages);
+      console.log('\nTemplates:');
+      console.log(templates);
+      console.log('\n' + '='.repeat(50));
+    }
+
+    if (context.eventName === 'pull_request') {
+      await createOrUpdateComment(context.issue.number);
+    } else if (context.eventName === 'push') {
+      const pullRequests = await github.rest.pulls.list({
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        state: 'open',
+        head: `${context.repo.owner}:${context.ref.replace('refs/heads/', '')}`
+      });
+
+      if (pullRequests.data.length > 0) {
+        await createOrUpdateComment(pullRequests.data[0].number);
+      } else {
+        console.log('No open pull request found for this push. Logging publish information to console:');
+        logPublishInfo();
+      }
+    }
+```
+
+This custom script does the following:
+
+- For pull requests: It creates or updates a comment with the publish information.
+- For pushes with an associated open PR: It adds or updates a comment on that PR.
+- For pushes without an open PR (e.g., direct pushes to main): It logs the publish information to the GitHub Actions console.
+
+By using this approach, you can:
+
+- Customize the format and content of the comments.
+- Control when and where comments are posted.
+- Handle different scenarios (PRs vs. direct pushes) differently.
+- Ensure publish information is always available, either as a PR comment or in the Actions log.
+
+Remember to set the necessary permissions in your workflow.
+
+This custom approach gives you full control over how pkg.pr.new communicates its results, allowing you to integrate it seamlessly into your development workflow.
+
 pkg.pr.new uses `npm pack --json` under the hood, in case you face issues, you can also use the `--pnpm` flag so it starts using `pnpm pack`. This is not necessary in most cases.
 
 <img width="100%" src="https://github.com/stackblitz-labs/pkg.pr.new/assets/37929992/2fc03b94-ebae-4c47-a271-03a4ad5d2449" />
@@ -222,10 +342,11 @@ on:
   pull_request:
   push:
     branches:
-      - '**'
+      - "**"
     tags:
-      - '!**'
+      - "!**"
 ```
+
 As noted in [#140](https://github.com/stackblitz-labs/pkg.pr.new/issues/140), workflows run on tags too, that's not an issue at all, but in case users would like to avoid duplicate publishes.
 
 ---