= Asciidoctor Project Site // Settings: ifdef::env-github[] :badges: endif::[] ifndef::env-github[:icons: font] ifdef::env-github[] :important-caption: :exclamation: endif::[] // URIs: :uri-letsencrypt: https://letsencrypt.org :uri-letsencrypt-article: https://fedoramagazine.org/letsencrypt-now-available-fedora/ :uri-netlify: https://www.netlify.com :uri-netlify-deploys: https://app.netlify.com/sites/asciidoctor/deploys
IMPORTANT: Are you looking for the Asciidoctor documentation or AsciiDoc Language documentation? They've moved! You can view the published documentation at https://docs.asciidoctor.org. To submit an issue or pull request to the Asciidoctor or AsciiDoc documentation, see the https://github.com/asciidoctor/asciidoctor[Asciidoctor repository] or https://github.com/asciidoctor/asciidoc-docs[AsciiDoc Language repository], respectively.
This is the project site for the https://asciidoctor.org[Asciidoctor project]. The site is composed in AsciiDoc, styled by https://github.com/foundation/foundation-sites/tree/v4.3.2[Foundation 4], baked with Awestruct, and hosted on {uri-netlify}[Netlify].
For instructions on how to install Awestruct and its dependencies, refer to the <
== Preview the site locally
To preview the site locally, simply run the default rake build task:
$ rake
The default rake build task is preview, so you're effectively typing:
$ rake preview
The preview task is just a short way of invoking Awestruct in development mode directly:
$ awestruct -d
Now visit http://localhost:4242 to preview the site.
To rebuild the site from a clean state, pass the --force flag to the preview task:
$ rake preview[--force]
You can pass any flag through to Awestruct using the syntax in the previous command.
If you just want to generate the site, run:
$ rake gen
//// === Set the JavaScript runtime
If you're building the site on Linux and Awestruct fails to locate a JavaScript runtime, you can either:
. install a node.js package or
. set the following environment variable in your shell profile scripts (e.g., ~/.bash_profile):
$ export EXECJS_RUNTIME=SpiderMonkey ////
== Add and commit files
Add new files (such as a new blog entry or image):
$ git add news/news-slug.adoc
or all new files present in a directory (it only affects new files, skips files already committed)
$ git add news/
Commit all files marked to be committed, including new files that were just added:
$ git commit -m 'your message here'
Commit all files that have changed, even if not marked to be committed:
$ git commit -a -m 'your message here'
Make sure there are no files that are "untracked" or "modified":
$ git status
You should see:
[.output] .... nothing to commit (working directory clean) ....
Now you are ready to deploy.
//// == Deploy the site to GitHub Pages
The following commands will push changes (git push), clean build the site (--force -g) using the production profile (-P production), then deploy it to github pages (--deploy):
$ git push && awestruct -P production --force -g --deploy
Or simply run the prepared rake build task (to deploy locally):
$ rake deploy
Or just push and let {uri-netlify-deploys}[Netlify] do the work of deploying the site:
$ rake push
If you want to push without triggering a publish, add the following to the commit message:
.... [ci skip] .... ////
== Install Awestruct
First, install https://rvm.io[RVM]. Trust me on this.
$ curl -#L https://get.rvm.io | bash -s stable --ruby
Next, setup an RVM gemset for working with the Asciidoctor site:
$ rvm use 2.7 --create
At this point, you could install Awestruct directly, but since the site build has some additional dependencies, it's best to let bundler handle the installation. Bundler will also ensure that you are using the correct versions of each gem when you run Awestruct.
$ bundle --path=.bundle/gems
You're now Awestruct!
== Hosting
This website is hosted on {uri-netlify}[Netlify] at the domain name asciidoctor.org. It's managed by the account docbot [at] asciidoctor [dot] org and other Asciidoctor administrators.
=== Deployment
Netlify also handles generating and deploying the site. Deployment is triggered via a webhook on the default branch of the git repository. The deploy job executes the following command:
$ rake deploy:netlify
The version of Ruby is set using an environment variable in the Netlify configuration.
The deploy logs for asciidoctor.org can be viewed at {uri-netlify-deploys}.
=== DNS
There are two DNS records that point asciidoctor.org and www.asciidoctor.org to the Netlify servers:
@ 3600 IN A 104.198.14.52 www 3600 IN CNAME asciidoctor.netlify.com.
The Netlify server automatically sets up a redirect that points from www.asciidoctor.org to asciidoctor.org.
=== TLS Certificate (https)
The TLS certificate for asciidoctor.org and www.asciidoctor.org was issued using {uri-letsencrypt}[Let's Encrypt] and is managed by {uri-netlify}[Netlify].
Verify the certificate is valid using:
$ curl -vI https://asciidoctor.org
Look for CN=asciidoctor.org under the "Server certificate" section.
Thanks to Netlify, the certificate will be regenerated automatically when it nears its expiry date.
== Licenses
The source code in this repository is licensed under the terms of the MIT license. See link:LICENSE[] to find the full license text.
The documentation content, located in the [.path]docs/ folder, is made available under the terms of a https://creativecommons.org/licenses/by/4.0/[Creative Commons Attribution 4.0 International License] (CC-BY-4.0).
See xref:NOTICE.adoc[NOTICE] for additional license, copyright, and trademark information.