These instructions will allow you to run the Elytron website locally for development and testing purposes.
The following steps are based on the Jekyll static site generator docs.
-
Install a full Ruby development environment
-
Install jekyll and bundler gems
gem install jekyll bundler
-
Fork the project repository, then clone your fork.
git clone git@github.com:YOUR_USER_NAME/wildfly-elytron.git
-
Change into the project directory:
cd wildfly-elytron
-
Checkout the develop branch:
git checkout develop
-
Use bundler to fetch all required gems in their respective versions
bundle install
-
Build the site and make it available on a local server
bundle exec jekyll serve
If you encounter the following message:
FATAL: Listen error: unable to monitor directories for changes.
Please refer to these instructions to fix this.
-
Now browse to http://localhost:4000/wildfly-elytron/
If you encounter any unexpected errors during the above, please refer to the troubleshooting page or the requirements page, as you might be missing development headers or other prerequisites.
For more regarding the use of Jekyll, please refer to the Jekyll Step by Step Tutorial.
To write a blog post:
- Add an author entry in _data/authors.yaml
- Your profile picture is fetched from the Gravatar service. Create an account,
and then associate your email with the account. Validate your picture with the email checker.
The field
emailhash
in authors.yaml is set using these instructions, or with the output from the following command:echo -n 'email@address.com' | awk '{NF=1;printf "%s", tolower($1);}' | md5sum - | awk 'NF=1'
- Your profile picture is fetched from the Gravatar service. Create an account,
and then associate your email with the account. Validate your picture with the email checker.
The field
- Create a blog post entry under _posts
- The file name should be
yyyy-mm-dd-slug.adoc
- The file name should be
- Your blog post should be in asciidoc format (take a look at other blogs posts in the _posts directory to see examples)
- To view your blog post without needing to build locally, the following steps can be used:
- If you haven't done so already, generate a fine-grained GitHub token following the instructions
here. Use this value to add a
PUSH_GITHUB_TOKEN
secret to your repository secrets (i.e., https://github.com/<YOUR_GITHUB_USERNAME>/wildfly-elytron/settings/secrets/actions).- You should set the Resource owner to your user account, and Repository access to "Only select repositories" and then your fork of
wildfly-elytron
. The only Repository permissions needed are "Access: Read and write" for Contents and Actions (this also enables "Access: Read" for Metadata, which is required).
- You should set the Resource owner to your user account, and Repository access to "Only select repositories" and then your fork of
- Simply push your changes to the
develop
branch on yourwildfly-elytron
fork. This will trigger a website build that will get pushed to thegh-pages
branch on your fork. Then browse to http://<YOUR_GITHUB_USERNAME>.github.io/wildfly-elytron/blog and click on your post.- The
gh-pages
branch must already exist in your fork before you can build the site. You can copy it from this repo by running these commands locally:git fetch upstream git checkout gh-pages # This should include a message that the branch is tracking upstream/gh-pages git push origin gh-pages
- The
- If you haven't done so already, generate a fine-grained GitHub token following the instructions
here. Use this value to add a
- To view your blog post locally, first follow the instructions above to build the Elytron website locally. Then browse to http://localhost:4000/wildfly-elytron/blog and click on your post.
- To view your blog post without needing to build locally, the following steps can be used:
- Submit a pull request against the
wildfly-elytron
develop
branch