Article

Processes file templates suitable for publication as articles, blogs, pages, etc.

Processed files may be uploaded to a Git repository of your choosing.

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

announce:
  # 
  article:

    # Enable or disable this announcer.
    # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `NEVER`.
    # 
    active: ALWAYS

    # Directory with file templates.
    # Defaults to `src/jreleaser/templates/article`.
    # Path must exist.
    # 
    templateDirectory: src/jreleaser/templates/article

    # Defines a list of files.
    # Each entry must define a path: field.
    # The path may be relative to templateDirectory or absolute.
    #  
    files:
      - path: path/to/some/file.md

    # Git author used to commit to the repository.
    # 
    commitAuthor:
      # Name used when authoring commits.
      # Defaults to `jreleaserbot`.
      # 
      name: jreleaserbot

      # E-mail used when authoring commits.
      # Defaults to `jreleaser@kordamp.org`.
      # 
      email: jreleaser@kordamp.org

    # Git repository to push the templates to.
    # Defaults are shown.
    # 
    repository:
      # Enables or disables the repository.
      # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      # Defaults to `RELEASE`.
      # 
      active: ALWAYS


      # The owner of the repository.
      # Defaults to the same owner as the release repository.
      # 
      owner: duke

      # The name of the repository.
      # Defaults to `duke-docs`.
      # 
      name: duke-docs

      # The target branch to use.
      # May define a `JRELEASER_ARTICLE_${GIT}_BRANCH` environment variable instead.
      # Defaults to the branch pointed by HEAD.
      #  
      branch: HEAD

      # Username used for authoring commits. Must have write access to the repository.
      # If left unspecified, the `JRELEASER_ARTICLE_${GIT}_USERNAME`
      # environment variable must be defined.
      # Defaults to the same username as the release repository.
      #  
      username: duke

      # Password or OAuth token with write access to the repository.
      # If left unspecified, the `JRELEASER_ARTICLE_${GIT}_TOKEN`
      # environment variable must be defined.
      #  
      token: __DO_NOT_SET_HERE__

      # Message when committing to the repository.
      # If left unspecified, `{{distributionName}} {{tagName}}` will be used.
      #  
      commitMessage: '{{distributionName}} {{tagName}}'

    # Additional properties used when evaluating templates.
    #  
    extraProperties:
      # Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
      foo: bar
# 
[announce.article]

  # Enable or disable this announcer.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  # 
  active = "ALWAYS"

  # Directory with file templates.
  # Defaults to `src/jreleaser/templates/article`.
  # Path must exist.
  # 
  templateDirectory = "src/jreleaser/templates/article"

  # Defines a list of files.
  # Each entry must define a path: field.
  # The path may be relative to templateDirectory or absolute.
  #  
  files = [
    { path = "path/to/some/file.md" }
  ]

  # Git author used to commit to the repository.

  # Name used when authoring commits.
  # Defaults to `jreleaserbot`.
  # 
  commitAuthor.name = "jreleaserbot"

  # E-mail used when authoring commits.
  # Defaults to `jreleaser@kordamp.org`.
  # 
  commitAuthor.email = "jreleaser@kordamp.org"

  # Git repository to push the templates to.
  # Defaults are shown.

  # Enables or disables the repository.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `RELEASE`.
  # 
  repository.active = "ALWAYS"


  # The owner of the repository.
  # Defaults to the same owner as the release repository.
  # 
  repository.owner = "duke"

  # The name of the repository.
  # Defaults to `duke-docs`.
  # 
  repository.name = "duke-docs"

  # The target branch to use.
  # May define a `JRELEASER_ARTICLE_${GIT}_BRANCH` environment variable instead.
  # Defaults to the branch pointed by HEAD.
  #  
  repository.branch = "HEAD"

  # Username used for authoring commits. Must have write access to the repository.
  # If left unspecified, the `JRELEASER_ARTICLE_${GIT}_USERNAME`
  # environment variable must be defined.
  # Defaults to the same username as the release repository.
  #  
  repository.username = "duke"

  # Password or OAuth token with write access to the repository.
  # If left unspecified, the `JRELEASER_ARTICLE_${GIT}_TOKEN`
  # environment variable must be defined.
  #  
  repository.token = "__DO_NOT_SET_HERE__"

  # Message when committing to the repository.
  # If left unspecified, `{{distributionName}} {{tagName}}` will be used.
  #  
  repository.commitMessage = "{{distributionName}} {{tagName}}"

  # Additional properties used when evaluating templates.
  #  
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
{
  "announce": {
    // 
    "article": {

      // Enable or disable this announcer.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // 
      "active": "ALWAYS",

      // Directory with file templates.
      // Defaults to `src/jreleaser/templates/article`.
      // Path must exist.
      // 
      "templateDirectory": "src/jreleaser/templates/article",

      // Defines a list of files.
      // Each entry must define a path: field.
      // The path may be relative to templateDirectory or absolute.
      //  
      "files": [
        {
          "path": "path/to/some/file.md"
        }
      ]

      // Git author used to commit to the repository.
      // 
      "commitAuthor": {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // 
        "name": "jreleaserbot",

        // E-mail used when authoring commits.
        // Defaults to `jreleaser@kordamp.org`.
        // 
        "email": "jreleaser@kordamp.org"
      },

      // Git repository to push the templates to.
      // Defaults are shown.
      // 
      "repository": {
        // Enables or disables the repository.
        // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `RELEASE`.
        // 
        "active": "ALWAYS",


        // The owner of the repository.
        // Defaults to the same owner as the release repository.
        // 
        "owner": "duke",

        // The name of the repository.
        // Defaults to `duke-docs`.
        // 
        "name": "duke-docs",

        // The target branch to use.
        // May define a `JRELEASER_ARTICLE_${GIT}_BRANCH` environment variable instead.
        // Defaults to the branch pointed by HEAD.
        //  
        "branch": "HEAD",

        // Username used for authoring commits. Must have write access to the repository.
        // If left unspecified, the `JRELEASER_ARTICLE_${GIT}_USERNAME`
        // environment variable must be defined.
        // Defaults to the same username as the release repository.
        //  
        "username": "duke",

        // Password or OAuth token with write access to the repository.
        // If left unspecified, the `JRELEASER_ARTICLE_${GIT}_TOKEN`
        // environment variable must be defined.
        //  
        "token": "__DO_NOT_SET_HERE__",

        // Message when committing to the repository.
        // If left unspecified, `{{distributionName}} {{tagName}}` will be used.
        //  
        "commitMessage": "{{distributionName}} {{tagName}}"
      },

      // Additional properties used when evaluating templates.
      //  
      "extraProperties": {
        // Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
        "foo": "bar"
      }
    }
  }
}
<jreleaser>
  <!--
    
  -->
  <announce>
    <!--
      
    -->
    <article>

      <!--
        Enable or disable this announcer.
        Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `NEVER`.
        
      -->
      <active>ALWAYS</active>

      <!--
        Directory with file templates.
        Defaults to `src/jreleaser/templates/article`.
        Path must exist.
        
      -->
      <templateDirectory>src/jreleaser/templates/article</templateDirectory>

      <!--
        Defines a list of files.
        Each entry must define a path: field.
        The path may be relative to templateDirectory or absolute.
         
      -->
      <files>
        <files>
          <path>path/to/some/file.md</path>
        <file>
      </files>

      <!--
        Git author used to commit to the repository.
        
      -->
      <commitAuthor>

        <!--
           Name used when authoring commits.
          Defaults to `jreleaserbot`.
          
        -->
        <name>jreleaserbot</name>

        <!--
          E-mail used when authoring commits.
          Defaults to `jreleaser@kordamp.org`.
          
        -->
        <email>jreleaser@kordamp.org</email>
      </commitAuthor>

      <!--
        Git repository to push the templates to.
        Defaults are shown.
        
      -->
      <repository>
        <!--
          Enables or disables the repository.
          Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
          Defaults to `RELEASE`.
          
        -->
        <active>ALWAYS</active>


        <!--
          The owner of the repository.
          Defaults to the same owner as the release repository.
          
        -->
        <owner>duke</owner>

        <!--
          The name of the repository.
          Defaults to `duke-docs`.
          
        -->
        <name>duke-docs</name>

        <!--
          The target branch to use.
          May define a `JRELEASER_ARTICLE_${GIT}_BRANCH`` environment variable instead.
          Defaults to the branch pointed by HEAD.
           
        -->
        <branch>HEAD</branch>

        <!--
          Username used for authoring commits. Must have write access to the repository.
          If left unspecified, the `JRELEASER_ARTICLE_${GIT}_USERNAME`
          environment variable must be defined.
          Defaults to the same username as the release repository.
           
        -->
        <username>duke</username>

        <!--
          Password or OAuth token with write access to the repository.
          If left unspecified, the `JRELEASER_ARTICLE_${GIT}_TOKEN`
          environment variable must be defined.
           
        -->
        <token>__DO_NOT_SET_HERE__</token>

        <!--
          Message when committing to the repository.
          If left unspecified, `{{distributionName}} {{tagName}}` will be used.
           
        -->
        <commitMessage>{{distributionName}} {{tagName}}</commitMessage>
      </repository>

      <!--
        Additional properties used when evaluating templates.
         
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>
    </article>
  </announce>
</jreleaser>
jreleaser {
  announce {
    // 
    article {

      // Enable or disable this announcer.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // 
      active = 'ALWAYS'

      // Directory with file templates.
      // Defaults to `src/jreleaser/templates/article`.
      // Path must exist.
      // 
      templateDirectory = 'src/jreleaser/templates/article'

      // Defines a list of files.
      // Each entry must define a path: field.
      // The path may be relative to templateDirectory or absolute.
      //  
      file {
        path = 'path/to/some/file.md'
      }

      // Git author used to commit to the repository.
      // 
      commitAuthor {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // 
        name = 'jreleaserbot'

        // E-mail used when authoring commits.
        // Defaults to `jreleaser@kordamp.org`.
        // 
        email = 'jreleaser@kordamp.org'
      }

      // Git repository to push the templates to.
      // Defaults are shown.
      // 
      repository {
        // Enables or disables the repository.
        // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `RELEASE`.
        // 
        active = 'ALWAYS'


        // The owner of the repository.
        // Defaults to the same owner as the release repository.
        // 
        owner = 'duke'

        // The name of the repository.
        // Defaults to `duke-docs`.
        // 
        name = 'duke-docs'

        // The target branch to use.
        // May define a `JRELEASER_BRANCH` environment variable instead.
        // Defaults to the branch pointed by HEAD.
        //  
        branch = 'HEAD'

        // Username used for authoring commits. Must have write access to the repository.
        // If left unspecified, the `JRELEASER_ARTICLE_${GIT}_USERNAME`
        // environment variable must be defined.
        // Defaults to the same username as the release repository.
        //  
        username = 'duke'

        // Password or OAuth token with write access to the repository.
        // If left unspecified, the `JRELEASER_ARTICLE_${GIT}_TOKEN`
        // environment variable must be defined.
        //  
        token = '__DO_NOT_SET_HERE__'

        # Message when committing to the repository.
        # If left unspecified, `{{distributionName}} {{tagName}}` will be used.
        #  
        commitMessage = '{{distributionName}} {{tagName}}'
      }

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
      //  
      extraProperties.put('foo', 'bar')
    }
  }
}

Example

Given a project configured as

jreleaser.yml
project:
  version: 1.2.3
  description: Sample application
  longDescription: Sample application
  website: https://github.com/duke/app
  authors:
    - Duke
  license: Apache-2.0
  java:
    groupId: com.acme
    version: 8
    mainClass: com.acme.Main
  extraProperties:
    inceptionYear: 2021

releaser:
  github:
    owner: duke

distributions:
  app:
    artifacts:
      - path: 'target/distributions/{{distributionName}}/{{distributionName}}-{{projectVersion}}.zip'

announce:
  article:
    active: always
    repository:
      name: docs
    files:
      - path: 'post.adoc'
        transform: '_posts/{{#f_now}}YYYY-MM-dd{{/f_now}}/{{projectName}}-{{#f_dash}}{{projectVersion}}{{/f_dash}}-released.adoc'

And file named post.adoc located at src/jreleaser/templates/article

---
layout: post
title: '{{projectNameCapitalized}} {{projectEffectiveVersion}} released'
date: {{#f_now}}YYYY-MM-dd{{/f_now}}
tags: release
synopsis: {{projectEffectiveVersion}} is the latest release.
author: duke
---

We just released {{projectNameCapitalized}} {{projectEffectiveVersion}} with a new round of bugfixes and documentation improvements.

== Full changelog

You can get {{releaseNotesUrl}}[the full changelog of {{projectEffectiveVersion}} on GitHub].

Generates the following file structure

out
└── jreleaser
    ├── output.properties
    ├── prepare
    │   └── article
    │       └── _posts
    │           └── 2021-07-26
    │               └── app-1-0-0-released.adoc
    ├── release
    │   └── CHANGELOG.md
    └── trace.log

The contents of the parsed template look like this

---
layout: post
title: 'App 1.2.3 released'
date: 2021-07-26
tags: release
synopsis: 1.0.0 is the latest release.
author: duke
---

We just released App 1.2.3 with a new round of bugfixes and documentation improvements.

== Full changelog

You can get https://github.com/duke/app/releases/tag/v1.2.3[the full changelog of 1.2.3 on GitHub].

This file will be uploaded to the https://github.com/duke/docs repository as _posts/2021-07-26/app-1-0-0-released.adoc.