github.com/darmach/terratest@v0.34.8-0.20210517103231-80931f95e3ff/docs/README.md (about) 1 # Terratest website 2 3 This is the code for the [Terratest website](https://terratest.gruntwork.io). 4 5 Terratest website is built with Jekyll and published on Github Pages from `docs` folder on `master` branch. 6 7 # Quick Start 8 9 ## Download project 10 11 Clone or fork Terratest [repository](https://github.com/gruntwork-io/terratest). 12 13 ## Run 14 15 1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/). Version 2.4 or above is recommended. 16 Consider using [rbenv](https://github.com/rbenv/rbenv) to manage Ruby versions. 17 18 2. Install `bundler`: 19 20 ```bash 21 gem install bundler 22 ``` 23 24 3. Go to the `docs` folder: 25 26 ```bash 27 cd docs 28 ``` 29 30 4. Install gems: 31 32 ```bash 33 bundle install 34 ``` 35 36 5. Run the docs site locally: 37 38 ```bash 39 bundle exec jekyll serve 40 ``` 41 42 6. Open [http://localhost:4000/](http://localhost:4000/) in your web browser. 43 44 # Deployment 45 46 GitHub Pages automatically rebuilds the website from the `/docs` folder whenever you commit and push changes to the `master` 47 branch. 48 49 # Working with the documentation 50 51 We recommend updating the documentation *before* updating any code (see [Readme Driven 52 Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)). This ensures the documentation 53 stays up to date and allows you to think through the problem at a high level before you get lost in the weeds of 54 coding. 55 56 The Terratest website contains *Docs* collection stored in `/docs/_docs`. 57 58 When you work with the documentation, it's good to preview the changes. To do that, run project as it is described in [Run section](#run). 59 60 1. [Change content on the existing page](#change-content-on-the-existing-page) 61 2. [Add a new page](#add-a-new-page) 62 3. [Remove or rename page](#remove-or-rename-page) 63 4. [Add custom redirection](#add-custom-redirection) 64 65 ## Change content on the existing page 66 67 1. Find page in `_docs` by file name (it's the same as page's title). 68 2. Edit content and save file. 69 70 ## Add a new page 71 72 1. Create a new file in `_docs`. The file's name and title have to be the same. 73 2. At the beginning of the file, add: 74 75 ``` 76 --- 77 layout: collection-browser-doc # X Cannot be changed 78 title: Quick start # <--- Change this 79 categories: 80 - getting-started # <--- Change this if needed 81 excerpt: Learn how to work with Terratest. # <--- Change page description 82 tags: ["Quick Start", "DRY", "backend", "CLI"] # <--- Set tags 83 order: 100 # <--- It sorts the docs on the list 84 nav_title: Documentation # X Cannot be changed 85 nav_title_link: /docs/ # X Cannot be changed 86 --- 87 88 ``` 89 90 * `layout` - do not change! (Layout sets components like a navigation sidebar, page header, footer, etc.) 91 * `title` - document title 92 * `categories` - the document's category. Four categories are in use for now: "getting-started", "testing-best-practices", "alternative-testing-tools", and "community". 93 * `excerpt` - description. Try to keep it short. 94 * `tags` - check other posts to see common tags, but you can set a new as well. 95 * `order` - it is used to sort the documents within collection. 96 * `nav_title` - the title displayed above navigation. It's optional and it's recommended to use the same as other files in the collection. 97 * `nav_title_link` - it is URL. If it is set, the `nav_title` becomes a link with a given URL. 98 99 3. Add content at the end of the file. 100 101 ## Remove or rename page 102 103 1. Find page in `_docs` by file name (it's the same as page's title). 104 2. Delete page or rename. 105 106 ## Add custom redirection 107 108 To add link to any page, including subpages outside of any collection, you can create a new file in specific collection (e.g. `_docs`), and set following content in the file: 109 110 ``` 111 --- 112 title: Support 113 categories: Community 114 excerpt: Need help? 115 tags: ["support"] 116 redirect_to: 117 - /support 118 order: 301 119 --- 120 ``` 121 122 123 ## Navigation 124 125 The navigation sidebar is built in `_includes/collection_browser/navigation/_collection_toc.html`. 126 127 First, the script groups documents of the given collection by categories. Categories make the uppermost level in the navigation sidebar. 128 Then, within each category, the script adds documents titles to the navigation under specific categories. Documents are sorted by `order` field set in frontmatter section. 129 Next, headings from each document are being extracted and added to the navigation. 130 131 # Development 132 133 ## Project structure 134 ``` 135 |-- _docs # docs *collection* 136 |-- _includes # partials 137 |-- _layouts # layouts 138 |-- _pages # static pages 139 | |-- 404 # "404: Not found" page 140 | |-- cookie-policy # "Cookie Policy" page 141 | |-- docs # index page for *_docs* collection 142 | |-- index # home page 143 | 144 |-- _posts # Posts collection - empty and not used 145 |-- _site # website generated by Jekyll 146 |-- assets # Javascript, Stylesheets, and images 147 |-- scripts # useful scripts to use in development 148 | |-- convert_md_to_adoc # contains the command to convert MD files to ADOC 149 | 150 |-- Gemfile 151 |-- _config.yml # Jekyll configuration file 152 ``` 153 154 ## Documentation and Examples collections 155 156 The [*documentation*](https://terratest.gruntwork.io/docs) is implemented as a Jekyll collection and built with [*Collection Browser*](#collection-browser). 157 158 ### Documentation collection 159 160 The index page of the *Docs* collection is in: `_pages/docs/index.html` and is available under `/docs` URL. It uses *Collection browser* from `_includes/collection_browser/browser` which makes the list of docs, adds search input with tag filter and puts navigation sidebar containing collection's categories. 161 162 Collection is stored in `_docs` folder. 163 164 ## Adding new pages to collections 165 166 The *Docs* collection uses *collection browser* which requires to setup proper meta tags in the doc file. 167 168 1. Create a new file in collection folder. *Docs* add to the `_docs`. 169 ``` 170 --- 171 layout: collection-browser-doc 172 title: CLI options # CHANGE THIS 173 categories: 174 - getting-started # CHANGE THIS 175 excerpt: >- # CHANGE THIS 176 Terratest example description 177 tags: ["CLI"] # CHANGE THIS 178 order: 102 # CHANGE THIS 179 nav_title: Documentation # OPTIONAL 180 nav_title_link: /docs/ # OPTIONAL 181 --- 182 ``` 183 184 * layout - always has to be: `collection-browser-doc` [DO NOT CHANGE] 185 * title - the doc title. 186 * categories - set one category. Use downcase with dashes, e.g. `getting-started`. 187 * excerpt - the doc description. 188 * tags - doc tags. 189 * order - it is use to list documents in the right order. "Getting Started" starts from 100, "Features" starts from 200, and "Community" starts from 300. 190 * nav_title - the title above navigation. It's optional. It's a link if `nav_title_link` is set. 191 * nav_title_link - it is a URL. If it is set, `nav_link` is transformed to the link. 192 193 ## Adding new collections 194 195 To add a new collection based on *Collection browser*, like *Docs* collection: 196 197 1. Add collection to the `_config.yml`: 198 ``` 199 collections: 200 my-collection: # --> Change to your collection's name 201 output: true 202 sort_by: order 203 permalink: /:collection/:categories/:title/ # --> You can adjust this to your needs. You can remove ":categories" if your collection doesn't use it. 204 ``` 205 2. Create a folder for collection in root directory, e.g: `_my-collection` (change name) 206 3. Add documents to the `_my-collection` folder and set proper meta tags (see: [Adding new docs to collections](#adding-new-docs-to-collections)). 207 4. Create folder for collection's index page in `_pages`. Use collection name, e.g: `_pages/my-collection`. 208 5. Add `index.html` file to newly create folder: 209 ``` 210 --- 211 layout: collection-browser # DO NOT CAHNGE THIS 212 title: Use cases 213 subtitle: Learn how to work with Terratest. 214 excerpt: Learn how to work with Terratest. 215 permalink: /examples/ 216 slug: examples 217 nav_title: Documentation # OPTIONAL 218 nav_title_link: /docs/ # OPTIONAL 219 --- 220 221 {% include collection_browser/browser.html collection=site.examples collection_name='examples' %} 222 ``` 223 6. Change `title`, `subtitle`, `excerpt`, `permalink`, and `slug` in meta tags. 224 7. In `include` statement, set `collection` to your collection set in `_config.yml` and set `collection_name`. 225 226 227 ## Collection Browser 228 229 _The Collection Browser is strongly inspired by implementation of `guides` on *gruntwork.io* website._ 230 231 The Collection Browser's purpose is to wrap Jekyll collection into: 232 * _index_ page containing ordered list of docs with search form, 233 * _show_ pages presenting docs' contents, and containing navigation sidebar, 234 * and build navigation sidebar. 235 236 ### Usage 237 238 1. Add collection to `_config.yml` 239 ``` 240 collections: 241 my-collection: # --> Change to your collection's name 242 output: true 243 sort_by: order 244 permalink: /:collection/:categories/:title/ # --> You can adjust this to your needs. You can remove ":categories" if your collection doesn't use it. 245 ``` 246 2. Create a folder for collection in root directory: `_my-collection` 247 3. Add documents (`.md` format is recommended) to the `_my-collection` folder. 248 4. In each document add: 249 ``` 250 --- 251 layout: collection-browser-doc # <-- It has to be "collection-browser-doc" 252 title: CLI options # <-- [CHANGE THIS] doc's title 253 categories: # <-- [CHANGE THIS] use single category. (Downcase and dashes instead of spaces) 254 - getting-started 255 excerpt: >- # <-- [CHANGE THIS] doc's description 256 Some description. 257 tags: ["CLI", "Another tag"] # <-- [CHANGE THIS] doc's tags 258 order: 102 # <-- [CHANGE THIS] set different number to each doc to set right order 259 --- 260 ``` 261 5. Create `index` page for collection. Create folder with collection name in `_pages`: `my-collection` 262 6. Add `index.html` in `_pages/my-collection`: 263 ``` 264 --- 265 layout: collection-browser # <-- It has to be "collection-browser" 266 title: Use cases 267 subtitle: Learn how to work with Terratest. 268 excerpt: Learn how to work with Terratest. 269 permalink: /use-cases/ 270 slug: use-cases 271 --- 272 273 {% include collection_browser/browser.html collection=site.my-collection collection_name='my-collection' %} 274 ``` 275 Adjust meta tags and replace `my-collection` with your collection name in `{% include ... %}` 276 277 ### How it works 278 279 The Collection Browser needs the _index_ page in `_pages` folder. It basically imports `browser.html` from `_includes/collection_browser`. 280 Meta tags, like `title`, `subtitle`, `excerpt`, are used by Collection Browser on _index_ page. The _index_ page is then published under URL assigned to `permalink`. 281 282 The _index_ page displays the list of collection's docs. Clicking on any of them, redirects user to the collection's doc page. 283 284 #### config.yml 285 286 Collections are registered in the `_config.yml` file like other typical Jekyll collections. 287 Additional field used in the configuration is: `sort_by: order`. It ensures that collection's documents are displayed in the right order. 288 The `order` is set then in every collection document. For large collections it's recommended to split files into several folders, and then to use 3-digit numbers. So each folder would have reserved range of numbers, like: `100 - 199`, `200-299`, etc. It makes easy to add new documents without overwriting `order` fields in other docs. 289 290 #### Layouts 291 292 The Collection Browser uses two layouts: 293 * `_layouts/collection-browser.html` - for the _index_ page containing the list of documents 294 * `_layouts/collection-browser-doc.html` - for the "_show_" page of collection's doc 295 296 #### Includes 297 298 All Collection Browser partials are stored in `_includes/collection_browser`. 299 * `browser.html` - it is the collection's _index_ page 300 * `_doc-page.html` - is a starting point for collection's document pages (_show_ pages) 301 302 Some includes may use partials from `_includes` directory. For example, `_includes/collection_browser/_cta-section.html` uses `_includes/links-n-built-by.html`. 303 304 #### Assets 305 306 Names of assets used by `collection-browser` in `assets` folder start with `collection-browser`. 307 308 Collection Browser's classes in stylesheets starts mostly with `cb`, `collection-browser` and `collection-browser-doc`. 309 310 Javascript files used by Collection Browser: 311 * `collection-browser_scroll.js` - responsible for the scroll spying in navigation sidebar and sticking this bar at the top of the screen when page is being scrolled. 312 * `collection-browser_search.js` - responsible for handling text search and tag filters. 313 * `collection-browser_toc.js` - responsible for opening and closing navigation sidebar on the document page. 314 315 #### Navigation Sidebar 316 317 The navigation sidebar is built in `_includes/collection_browser/navigation/_collection_toc.html`. Read more: [Navigation](#navigation) 318 319 ## Markdown (md) > AsciiDoc (adoc) converter 320 321 Recommended format of documents is Github Markdown (`.md`). If you use the Markdown format (`.md`), and you want to convert to AsciiDoc format, you can do this with *Pandoc*: 322 323 1. Create `input.md` file and paste there Markdown content 324 2. Run: 325 ``` 326 $ pandoc --from=gfm --to=asciidoc --wrap=none --atx-headers input.md > output.adoc 327 ``` 328 3. The converted content in `.adoc` format is printed in `output.adoc` 329 330 You can use also `scripts/convert_md_to_adoc.sh`. 331 332 ## AsciiDoc (adoc) > Markdown (md) converter 333 334 To convert from `.adoc` (AsciiDoc) format to Markdown, you need *AsciiDoctor* and *Pandoc*. 335 336 First, install Asciidoctor: 337 ``` 338 $ sudo apt-get install asciidoctor 339 ``` 340 341 Next, install Pandoc: 342 https://pandoc.org/installing.html 343 344 Then you can use script: `scripts/convert_adoc_to_md.sh` or use the command: 345 346 ``` 347 $ asciidoctor -b docbook input.adoc && pandoc -f docbook -t gfm input.xml -o output.md --wrap=none --atx-headers 348 ``` 349 350 In both cases: 351 1. create a file: `input.adoc`, 352 2. add content to the file, 353 3. run script or command, 354 4. The output can be found in `output.md`.