Merge pull request #67 from jenmalloy/add-external-url-variables

added variables for external book links and added build script

book-product.json

@@ -12,7 +12,9 @@
     "title": "Server Administration Guide",
     "project": {
       "name": "Red Hat Single Sign-On",
-      "version": "7.1.0"
+      "version": "7.1.0",
+      "doc_base_url": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/",
+      "doc_info_version_url": "7.1-Beta"
     },
     "community": false,
     "product": true,
@@ -20,16 +22,16 @@
 
     "developerguide": {
       "name": "Server Developer Guide",
-      "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1-Beta/server-developer-guide/"
+      "link": "/single/server-developer-guide/"
 
     },
     "installguide": {
       "name": "Server Installation and Configuration Guide",
-      "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1-Beta/server-installation-and-configuration-guide/"
+      "link": "/single/server-installation-and-configuration-guide/"
     },
     "adapterguide": {
       "name": "Securing Applications and Services Guide",
-      "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1-Beta/securing-applications-and-services-guide/"
+      "link": "/single/securing-applications-and-services-guide/"
     }
   }
 }

buildGuide.sh

@@ -0,0 +1,69 @@
+# Build the guide
+
+# Find the directory name and full path
+CURRENT_GUIDE=${PWD##*/}
+CURRENT_DIRECTORY=$(pwd)
+
+usage(){
+  cat <<EOM
+USAGE: $0 [OPTION]
+
+DESCRIPTION: Build the documentation in this directory.
+
+OPTIONS:
+  -h       Print help.
+
+EOM
+}
+
+while getopts "ht:" c
+ do
+     case "$c" in
+       h)         usage
+                  exit 1;;
+       \?)        echo "Unknown option: -$OPTARG." >&2
+                  usage
+                  exit 1;;
+     esac
+done
+
+if [ ! -d target ]; then
+   echo "You must run 'python gitlab-conversion.py' to convert the content before you run this script."
+   exit
+fi
+
+# Remove the html and build directories and then recreate the html/images/ directory
+if [ -d target/html ]; then
+-   rm -r target/html/
+fi
+if [ -d target/html ]; then
+   rm -r target/html/
+fi
+
+mkdir -p html
+cp -r target/images/ target/html/
+
+echo ""
+echo "********************************************"
+echo " Building $CURRENT_GUIDE                "
+echo "********************************************"
+echo ""
+echo "Building an asciidoctor version of the guide"
+asciidoctor -t -dbook -a toc -o target/html/$CURRENT_GUIDE.html target/master.adoc
+
+echo ""
+echo "Building a ccutil version of the guide"
+ccutil compile --lang en_US --format html-single --main-file target/master.adoc
+
+cd ..
+
+echo "View the asciidoctor build here: " file://$CURRENT_DIRECTORY/target/html/$CURRENT_GUIDE.html
+
+if [ -d  $CURRENT_DIRECTORY/build/tmp/en-US/html-single/ ]; then
+  echo "View the ccutil build here: " file://$CURRENT_DIRECTORY/build/tmp/en-US/html-single/index.html
+  exit 0
+else
+  echo -e "${RED}Build using ccutil failed!"
+  echo -e "${BLACK}See the log above for details."
+  exit 1
+fi

topics/MigrationFromOlderVersions.adoc

@@ -37,7 +37,7 @@ tags under the keycloak subsystem.  Before migration, your keycloak subsystem sh
 </subsystem>
 ----
 
-The jboss-cli tool is discussed in detail in link:{{book.installguide.link}}[{{book.installguide.name}}].
+The jboss-cli tool is discussed in detail in link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.installguide.link}}[{{book.installguide.name}}].
 
 ==== migrate-json in Standalone Mode
 

topics/account.adoc

@@ -9,7 +9,7 @@ change their credentials, update their profile, and view their login sessions.
 image:../{{book.images}}/account-service-profile.png[]
 
 The initial page is the user's profile, which is the `Account` left menu item.  This is where they specify basic data about themselves.  This screen can be extended
-to allow the user to manage additional attributes.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more details.
+to allow the user to manage additional attributes.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] for more details.
 
 The `Password` left menu item allows the user to change their password.
 
@@ -42,4 +42,4 @@ image:../{{book.images}}/account-service-apps.png[]
 === Themeable
 
 Like all UIs in {{book.project.name}}, the User Account Service is completely themeable and internationalizable.
-See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more details.
+See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] for more details.

topics/authentication/password-policies.adoc

@@ -32,7 +32,7 @@ Here's an explanation of each policy type:
 {% if book.community %}
 HashAlgorithm::
   Passwords are not stored as clear text.  Instead they are hashed using standard hashing algorithms before they are stored or validated.
-  The only built-in and default algorithm available is PBKDF2.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
+  The only built-in and default algorithm available is PBKDF2.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}]
   on how to plug in your own algorithm.  Note that if you do change the algorithm, password hashes will not change in storage until
   the next time the user logs in.
 {% endif %}

topics/clients/client-oidc.adoc

@@ -36,7 +36,7 @@ This specifies an alpha-numeric string that will be used as the client identifie
 *Name*
 
 This is the display name for the client whenever it is displayed in a {{book.project.name}} UI screen.  You can localize
-the value of this field by setting up a replacement string value i.e. $\{myapp}.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
+the value of this field by setting up a replacement string value i.e. $\{myapp}.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}]
 for more information.
 
 *Description*
@@ -104,7 +104,7 @@ If this is on, clients are allowed to use the OIDC <<fake/../../sso-protocols/oi
 For {{book.project.name}} specific client adapters, this is the callback endpoint for the client.  The {{book.project.name}}
 server will use this URI to make callbacks like pushing revocation policies, performing backchannel logout, and other
 administrative operations.  For {{book.project.name}} servlet adapters, this can be the root URL of the servlet application.
-See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
+For more information see link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.adapterguide.link}}[{{book.adapterguide.name}}].
 
 *Web Origins*
 
@@ -118,7 +118,7 @@ This protocol exists to protect against XSS, CSRF and other JavaScript-based att
 `Web Origins` setting for the client are embedded within the access token sent to the client application.  The client
 application can then use this information to decide whether or not to allow a CORS request to be invoked on it.  This is
 an extension to the OIDC protocol so only {{book.project.name}} client adapters support this feature.
-See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
+See link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
 
 To fill in the `Web Origins` data, enter in a base URL and click the + sign to add.  Click the - sign next to URLs you want to remove.
 Remember that you still have to click the `Save` button!

topics/clients/client-saml.adoc

@@ -37,7 +37,7 @@ Client ID::
 
 Name::
   This is the display name for the client whenever it is displayed in a {{book.project.name}} UI screen.  You can localize
-  the value of this field by setting up a replacement string value i.e. $\{myapp}.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
+  the value of this field by setting up a replacement string value i.e. $\{myapp}.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}]
   for more information.
 
 Description::

topics/clients/oidc/confidential.adoc

@@ -43,7 +43,7 @@ client publishes it's public key in https://self-issued.info/docs/draft-ietf-jos
 client changes it's keys, {{book.project.name}} will automatically download them without need to re-import anything on {{book.project.name}} side.
 
 If you use client secured by {{book.project.name}} adapter, you can configure the JWKS URL like https://myhost.com/myapp/k_jwks assuming that https://myhost.com/myapp is the
-root URL of your client application. See {{book.developerguide.link}}[{{book.developerguide.name}}] for additional details.
+root URL of your client application. See {{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] for additional details.
 
 WARNING: For the performance purposes, {{book.project.name}} caches the public keys of the OIDC clients. If you think that private key of your client
 was compromised, it is obviously good to update your keys, but it's also good to clear the keys cache. See <<fake/../../realms/cache.adoc#_clear-cache, Clearing the cache>>

topics/clients/protocol-mappers.adoc

@@ -34,7 +34,7 @@ Consent Required::
 Consent Text::
   If your client requires consent and the `Consent` switch is on, this is the text that will be displayed by the user.
   The value for this text is localizable by specifying a substitution variable with `$\{var-name}` strings.  The
-  localized value is then configured within property files in your theme.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
+  localized value is then configured within property files in your theme.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}]
   for more information on localization.
 
 Most OIDC mappers also allow you to control where the claim gets put.  You can opt to include or exclude the claim from both the

topics/events/login.adoc

@@ -104,5 +104,5 @@ that comes with your distribution and adding for example:
 </spi>
 ----
 
-See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on
+See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.installguide.link}}[{{book.installguide.name}}] for more details on
 where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives.

topics/identity-broker/first-login-flow.adoc

@@ -24,7 +24,7 @@ You can re-configure the existing flow. (For example you can disable some authen
 
 {% if project.community %}
 You can also create a new authentication flow and/or write your own Authenticator implementations and use it in your flow.
-See link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more details.
+See link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] for more details.
 {% endif %}
 
 ==== Default First Login Flow

topics/initialization.adoc

@@ -1,7 +1,7 @@
 
 == Server Initialization
 
-After performing all the installation and configuration tasks defined in the link:{{book.installguide.link}}[{{book.installguide.name}}],
+After performing all the installation and configuration tasks defined in the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.installguide.link}}[{{book.installguide.name}}],
 you will need to create an initial admin account.
 {{book.project.name}} does not have any configured admin account out of the box.
 This account will allow you to create an admin that can log into the _master_ realm's administration console so that

topics/login-settings/forgot-password.adoc

@@ -19,7 +19,7 @@ to a page where they can enter in their username or email and receive an email w
 image:../../{{book.images}}/forgot-password-page.png[]
 
 The text sent in the email is completely configurable. You just need to extend or edit the theme associated with it.
-See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information.
+See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] for more information.
 
 When the user clicks on the email link, they will be asked to update their password, and, if they have an OTP generator
 set up, they will also be asked to reconfigure this as well.  Depending on the security requirements of your organization

topics/realms/themes.adoc

@@ -21,12 +21,12 @@ Email Theme::
 
 
 
-The link:{{book.developerguide.link}}[{{book.developerguide.name}}] goes into how to create a new themes or modify existing ones.
+The link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] goes into how to create a new themes or modify existing ones.
 
 ==== Internationalization
 
 Every UI screen is internationalized in {{book.project.name}}.  The default language is English, but if you turn on the
 `Internationalization` switch on the `Theme` tab you can choose which locales you want to support and what the default locale
 will be.  The next time a user logs in, they will be able to choose a language on the login page to use for the login screens,
-User Account Management UI, and Admin Console.  The link:{{book.developerguide.link}}[{{book.developerguide.name}}] explains
+User Account Management UI, and Admin Console.  The link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] explains
 how you can offer additional languages.

topics/roles/realm-roles.adoc

@@ -13,7 +13,7 @@ and hit the `Save` button.
 image:../../{{book.images}}/role.png[]
 
 The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}` strings.
-The localized value is then configured within property files in your theme.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
+The localized value is then configured within property files in your theme.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}]
 for more information on localization.  If a client requires user _consent_, this description string will be displayed on the
 consent page for the user.
 

topics/user-federation/ldap.adoc

@@ -56,7 +56,7 @@ When you configure a secured connection URL to your LDAP store(for example `ldap
 {{book.project.name}} will use SSL for the communication with LDAP server.
 The important thing is to properly configure a truststore on the {{book.project.name}} server side, otherwise {{book.project.name}} can't trust the SSL connection to LDAP.
 
-The global truststore for the {{book.project.name}} can be configured with the Truststore SPI.  Please check out the link:{{book.installguide.link}}[{{book.installguide.name}}] for more detail.
+The global truststore for the {{book.project.name}} can be configured with the Truststore SPI.  Please check out the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.installguide.link}}[{{book.installguide.name}}] for more detail.
 If you don't configure the truststore SPI, the truststore will fallback to the default mechanism provided by Java (either the file provided by system property `javax.net.ssl.trustStore`
 or the cacerts file from the JDK if the system property is not set).
 

topics/users/recaptcha.adoc

@@ -33,5 +33,5 @@ values of both the `X-Frame-Options` and `Content-Security-Policy` headers.
 image:../../{{book.images}}/security-headers.png[]
 
 Once you do this, reCAPTCHA should show up on your registration page.  You may want to edit _register.ftl_ in your login
-theme to muck around with the placement and styling of the reCAPTCHA button.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
+theme to muck around with the placement and styling of the reCAPTCHA button.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}]
 for more information on extending and creating themes.

topics/users/required-actions.adoc

@@ -39,5 +39,5 @@ Simply click the checkbox in the `Default Action` column of the required actions
 Many organizations have a requirement that when a new user logs in for the first time, they need to agree to the terms and conditions
 of the website.  {{book.project.name}} has this functionality implemented as a required action, but it requires some configuration.  For one, you
 have to go to the `Required Actions` tab described earlier and enable the `Terms and Conditions` action.  You must also edit the
-_terms.ftl_ file in the _base_ login theme.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information on extending and
+_terms.ftl_ file in the _base_ login theme.  See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] for more information on extending and
 creating themes.

topics/users/user-registration.adoc

@@ -22,6 +22,6 @@ and a new password.
 image:../../{{book.images}}/registration-form.png[]
 
 You can change the look and feel of the registration form as well as removing or adding additional fields that must be entered.
-See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information.
+See the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.developerguide.link}}[{{book.developerguide.name}}] for more information.