GitHub Action: action-itemplate-ghpages

This action can automatically publish auto-filled GitHub Pages using basic data from your repository.

It can be used with some pre-build themes or you can customize the generated pages with your own custom templates (using ITemplate).

GitHub Pages

GitHub Pages can be stored on any branch and in the root folder or in /docs folder. This action supports all of these options, but it is recommended to use the gh-pages branch and /docs folder.

Simple usage: themes

This action have some pre-build Themes that can be used. This is the simplest way to use it.

To use a theme, in the templates_folder input (see the section Simple Workflow Using a Theme below), you put only the name of the theme you want to use enclosed by ":".

For example: to use the 'light' theme, you need to set:

templates_folder: ':light:'

Available themes are:

• :reference:
• :light:
• :dark:
• :bluish:
• :greenish:
• :purplish:
• :grayish:
• :hellish:
• :greenscreen:

(You can see a screenshot of the themes in the Themes page).

Configuration

The recomended configuration for your GitHub Pages:

• create a branch named gh-pages for your pages
• configure your pages in the gh-pages branch (Repository Settings > Pages > Source)
• point your pages to the docs folder in the settings

To avoid the Jekyll processing of your GitHub Pages, you need to create an empty file named .nojekyll in the root of your pages folder. If you followed the recomendations above, it needs to be in docs/.nojekyll at the gh-pages branch.

Simple Workflow Using a Theme

You need to create a workflow in your repository Actions to use this action, like this one:

name: Automatic GitHub Pages generation

on:
  # Trigger on page_build, as well as release, fork, push, watch and issues events
  page_build:
  release:
  fork:
  push:
  watch:
  issues:
    types:
      - opened
      - closed
      - edited
      - deleted
jobs:
  deploy-pages:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        # The branch where the templates are stored
        # (if not present, uses the 'master' branch)
        # (recomended: use the same branch configured to be used in GH Pages)
        ref: 'gh-pages'
    - uses: itamarc/action-itemplate-ghpages@v1
      with:
        templates_folder: ':light:'
        pages_branch: 'gh-pages'
        pages_folder: 'docs'
        # Change to your time zone
        timezone: 'America/Sao_Paulo'
      env:
        # Needed to publish the pages
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

(More details about these inputs in the workflow and others are below in the Action Inputs section)

Optional features

If you want to publish your README.md file, you need to enable the publish_readme_md option. If set to 'true', the action will publish the README.md file from the repository root in the generated page as README.html and put a link to it in the generated page. If set to 'inline', the README.md file will be included in the generated index.html file.

If you want to publish some additional content, you need to add them to the content_to_copy option. This can be used, for example, to copy images referenced in the README.md file. If this content includes other Markdown files, you may want to set the convert_md_to_html option to 'true' to not only convert the files but also convert the links to them from ".md" to ".html", in all these files and in the README.html file as well.

You can also want to automatically copy the README.md file from the master branch to the gh-pages branch. To do that, see the Tips section below.

Advanced usage: custom templates

You can create your own templates and use them with this action.

Suggestion: you can copy a pre-built theme you want to use and modify it. In the action repository, you can find the pre-built themes in the themes folder. Look at the folder with the name of the theme you want to use and also the files in common folder.

Configuration

The recomended configuration for your GitHub Pages:

• put your templates and your pages in a branch of their own (for example: gh-pages)
• point your pages to the docs folder in the settings
• put your templates in a folder outside the docs folder (for example: templates)
• if you want to use snippets, put them in a separate folder (for example: snippets)

To avoid the Jekyll processing of your GitHub Pages, you need to create an empty file named .nojekyll in the root of your pages folder. If you followed the recomendations above, it will be in docs/.nojekyll.

Action Inputs

This action can be configured with the following inputs:

Full Workflow

To use the action, you need to create a workflow like the one below. The checkout step is required to the action to have access to your templates and to be able to commit back the changed pages.

name: Automatic GitHub Pages generation

on:
  # Trigger on page_build, as well as release, fork, push, watch and issues events
  page_build:
  release:
  fork:
  push:
  watch:
  issues:
    types:
      - opened
      - closed
      - edited
      - deleted
jobs:
  deploy-pages:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        # The branch where the templates are stored
        # (if not present, uses the 'master' branch)
        # (recomended: use the same branch configured to be used in GH Pages)
        ref: 'gh-pages'
    - uses: itamarc/action-itemplate-ghpages@v1
      with:
        templates_folder: 'templates'
        allow_templates_subfolders: 'false'
        snippets_folder: 'snippets'
        pages_branch: 'gh-pages'
        pages_folder: 'docs'
        # Change to your time zone
        timezone: 'America/Sao_Paulo'
        max_issues: '5'
        max_collaborators: '20'
        publish_readme_md: 'true'
        content_to_copy: ''
        syntax_highlight_enable: 'true'
        syntax_highlight_theme: 'default'
        log_level: 'INFO'
      env:
        # Needed to publish the pages
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Template files

The templates are in the format supported by ITemplate.

If your template files have the sequence ".tmpl" in the name, it will be removed. For example, if you have a template file called index.tmpl.html, the resulting file will have the name index.html. Otherwise, the name is not changed.

Snippets

If the parameter snippets_foler is set, the files in this folder will be processed first and their filled content will be available to the templates using as key the file name until the first character "." (dot) preceded by SNP_.

Example: if there is in the snippets folder a file named RELEASES.html (or RELEASES.tmpl.html or RELEASES.snp.html), it will be processed and its content will be available when processing the templates with the key SNP_RELEASES.

The snippets folder will not be recursive, all snippets must be in the same folder, without subfolders.

Snippets will not be saved in any way to the destination folder.

Markdown

If you have a template or snippet with extension .md, it will:

1. Be filled using ITemplate
2. Be converted to HTML
3. If it's a template, be saved in the destination with .html extension instead of .md

If it's a template, the resulting HTML file will be completed with header and footer (the footer will be only </body></html>).

If you're using a built-in theme, it will use the theme's CSS.

If you're using a custom set of templates and you want a custom header for your Markdown files (for example, to define a specific CSS), create a snippet with name MARKDOWN_HEADER (it will be used internally using the key SNP_MARKDOWN_HEADER and will be available to be used in the templates). Include in this file everything that you want including a <body> tag.

Publishing the README.md

You can export the README.md file from your GitHub Pages branch (be careful to don't edit only the one in master or main branch, unless this is the source for your Pages - not recommended) using the action parameter publish_readme_md.

This parameter can have the following values:

• true: the README.md will be converted and published as a separate file README.html. If you're using a built-in theme, the generated page will have a link to it.
• inline: the README.md will be exported available as a snippet with key SNP_README. If you're using a built-in theme, the content will be included in the generated page.
• false: the README.md will not be published

If set to true, it will be completed with header and footer as described in Markdown section. If you want a custom header, you can use the MARKDOWN_HEADER snippet or an specific one with the name README_HEADER (this last one will have precedence if it exists).

To automatically copy the README.md file from the master branch to your pages branch, you can use the planetoftheweb/copy-to-branches action. See the Tips section below for details.

Syntax Highlight

When converting a Markdown file to HTML, the code blocks will be converted to HTML tag <pre><code class="language-xxx">...</code></pre> where xxx is the language name defined in the Markdown code block.

You can use this also in your custom templates. If you're using your own templates and have the syntax highlight enabled, the following snippets will be available for you to insert the code needed: SNP_SYNTAX_HIGHLIGHT_CSS to your <head> section and SNP_SYNTAX_HIGHLIGHT_JS in the end of your <body> section. The appropriate CSS and JS files will be copied automatically.

To enable the syntax highlight for these code blocks, you need to set the input syntax_highlight_enable to true.

If you want to use a theme different from default, you need to set the input syntax_highlight_theme to the name of the theme you want to use.

The following themes from PrismJS are supported: default, coy, dark, funky, okaidia, solarizedlight, tomorrow, twilight.

The following languages are supported in this Action: Markup, Clike, Javascript, Actionscript, Apacheconf, Sql, Applescript, C, Arduino, Autohotkey, Autoit, Basic, Batch, Bbcode/shortcode, Csharp/dotnet/cs, Cmake, Cobol, Csv, Lua, Erlang, Excel-formula/xls, Fortran, Git, Graphql, Ini, Javastacktrace, Json, Jsonp, Jsstacktrace, Julia, Log, Makefile, Matlab, Objectivec, Pascal/objectpascal, Perl, Php, Powershell, Properties, Python, R, Rest, Scala, Iecst, Swift, Vbnet, Vim, Visual-basic/vba, Wolfram/mathematica/wl/nb.

I didn't insert all languages from PrismJS to avoid the overhead in the JS file size.

If you need to add a new language supported by PrismJS, you can open an Issue and I'll add it ASAP.

Publishing additional content

If you set the content_to_copy parameter, the files or folders specified will be copied when publishing, keeping the relative path, without change.

This input parameter needs to have the relative path to the files or folders you want to copy separated by spaces.

For example, if you want to copy the images folder and the help.html file from the www folder, you can set the parameter as:

content_to_copy: 'images www/help.html'

Available data

The templates and the snippets can use any of the keys in the next sections.

From the GitHub API

Calculated

From the parameters

Those keys are the parameters you passed to the action, and you can find an utility for them in your templates.

From the environment

Those keys are mostly for the use of the action itself, but since it's there, maybe you can use them somehow.

Tips

• If you're maintaing your Pages in the 'gh-pages' branch, you can use the planetoftheweb/copy-to-branches action to copy your README.md and other files from master to the gh-pages branch before generating the pages. To do so, you can add the following job to your workflow before the job that generates the pages:

  update-docs-on-gh-pages-branch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          # Adjust the depth as needed according to the files you want to copy
          fetch-depth: 0
      - name: Copy To Branches Action
        uses: planetoftheweb/copy-to-branches@v1.1
        env:
          # The branch where the files will be copied from
          key: 'master'
          # The destination branch
          branches: 'gh-pages'
          # The files that will be copied with the relative path, separated by spaces
          files: 'README.md'

• The page describing this Action was created using itself. So, if you want to see a page generated by this Action, you can access it at https://itamarc.github.io/action-itemplate-ghpages/

Credits

(c) 2021 Itamar Carvalho

This work uses the following packages and softwares:

• io.github.itamarc:itemplate version 1.2
• org.json:json version 20210307
• org.apache.httpcomponents:httpclient version 4.5.13
• com.vladsch.flexmark:flexmark-all version 0.62.2
• Docker
• Apache Maven
• GitHub GraphQL API
• GitHub Actions
• bash
• git
• Prism.js

Licence

This project is under GNU GPL v3.0