Read Me

siteleaf-updater

siteleaf-updater

GitHub Workflow Status (branch) Renovate Status Libraries.io dependency status for latest release Snyk Vulnerabilities for npm package JavaScript Style Guide CodeFactor node-current NPM version NPM Downloads GitHub License GitHub last commit

update the index file of your project’s siteleaf project with your repository’s README.md file

Why it is necessary

When hosting GitHub Pages, there is a common discrepancy one faces when choosing the place to host their page files.

1. Host it on the master branch

Hosting GitHub Pages the master branch has the advantage that files can be shared with the project (including the README). However, pages usually stand alone without a dependency to or from the project’s files. Hence, there might be numerous commits that cause an avoidable overhead to merges, CI, and pulls.

2. Host it on a dedicated branch

Hosting the pages on a dedicated branch (e.g., gh-pages) has the benefit that this beforementioned overhead is avoided. Separate concerns are rooted in separate trees, just as it is supposed to be. However, normally, developers only want to publish their README with a few additions. There is no integrated way or known method in GitHub to sync the README file without hooks or different workarounds. This circumstance impairs common maintenance and automation requirements.

Solution

  1. Use Siteleaf, and publish or sync to a dedicated branch on GitHub.
  2. Create a page and assign it a path (i.e. index by default).
  3. Setup your CI to use siteleaf-updater for automated doc updates.

Parameters

Action Input CLI Parameter Environment Variable Default Description
api-key api-key SITELEAF_API_KEY required the API key that grants access to the repository’s siteleaf project
api-secret api-secret SITELEAF_API_SECRET required the API secret that grants access to the repository’s siteleaf project
site site SITELEAF_SITE required the id of the siteleaf site to be updated
page page SITELEAF_PAGE index the target page of the siteleaf site to be updated
file file SITELEAF_MD_SOURCE README.md the path to the local Markdown file to push
publish publish - false allows publishing the site after its update

Action Example

steps:
  - name: update site
    uses: gofunky/siteleaf-updater@v2
    with:
      api-key: $
      api-secret: $
      site: 'my-site'
      page: 'contribution'
      file: 'CONTRIBUTION.md'
      publish: true