|
| 1 | +--- |
| 2 | +title: Getting Started |
| 3 | +tags: |
| 4 | + - jekyll |
| 5 | + - github |
| 6 | + - github-pages |
| 7 | +--- |
| 8 | + |
| 9 | +# Getting Started |
| 10 | + |
| 11 | +## Features |
| 12 | + |
| 13 | +### User Interaction |
| 14 | + |
| 15 | +If you look at any header field on the page, you'll notice three little dots |
| 16 | +(called an elipsis) that if you mouse over, will open up to give you options |
| 17 | +for Permalink, Edit this Page, and Ask a Question. |
| 18 | +These are to ensure that a user is able to link someone else directly to a section |
| 19 | +of interest (Permalink), contribute a fix or suggestion to the documentation itself on GitHub |
| 20 | +(Edit this page) or open up an issue that links directly to where the user has |
| 21 | +the question. Documentation is hard, and sometimes unclear, and the site |
| 22 | +should make it easy to ask a question or suggest a change. |
| 23 | + |
| 24 | +### Search |
| 25 | + |
| 26 | +The entire site, including posts and documentation, is indexed and then available |
| 27 | +for search at the top of the page. Give it a try! The content is rendered |
| 28 | +from [this file](https://github.com/vsoch/mkdocs-jekyll/blob/master/search/search_index.json) |
| 29 | +into [this json data structure](https://vsoch.github.io/mkdocs-jekyll/search/search_index.json) |
| 30 | +that feeds into the search defined in `assets/js/application.js`. If you want to |
| 31 | +exclude any file from search, add this to its front end matter: |
| 32 | + |
| 33 | +--- |
| 34 | +layout: null |
| 35 | +excluded_in_search: true |
| 36 | +--- |
| 37 | + |
| 38 | +The example above is for a css file in the assets folder that is used as a template, |
| 39 | +but should not be included in search. |
| 40 | + |
| 41 | +### External Search |
| 42 | + |
| 43 | +If you have an external site with a search GET endpoint (meaning one that ends |
| 44 | +in `?q=<term>`, then you can automatically link page tags to search this endpoint. |
| 45 | +For example, on an HPC site I'd want a tag like "mpi" to do a search on |
| 46 | +[http://ask.cyberinfrastructure.org](http://ask.cyberinfrastructure.org) for mpi. |
| 47 | +See the [tags](#tags) section below for how to configure this. |
| 48 | + |
| 49 | +### Documentation |
| 50 | + |
| 51 | +Documentation pages should be written in the `docs` folder of the repository, |
| 52 | +and you are allowed to use whatever level of nesting (subfolders) that |
| 53 | +works for you! It's a Jekyll [collection](https://jekyllrb.com/docs/collections/), which means that you |
| 54 | +can add other content (images, scripts) and it will be included for linking to. |
| 55 | + |
| 56 | +#### Organization |
| 57 | + |
| 58 | +The url that will render is based on the path. For example, if we had the following structure: |
| 59 | + |
| 60 | +``` |
| 61 | +docs/ |
| 62 | + getting-started.md |
| 63 | + clusters/ |
| 64 | + sherlock/ |
| 65 | + getting-started.md |
| 66 | +``` |
| 67 | + |
| 68 | +The first page (akin to the one you are reading) would render at it's path, |
| 69 | +`/docs/getting-started/`. |
| 70 | + |
| 71 | + |
| 72 | +#### Linking |
| 73 | + |
| 74 | +From that page, we could provide the |
| 75 | +direct path in markdown to any subfolder to link to it, such as the second |
| 76 | +getting started page for sherlock: |
| 77 | + |
| 78 | +``` |
| 79 | +{% raw %}[example](clusters/sherlock/getting-started.md){% endraw %} |
| 80 | +``` |
| 81 | + |
| 82 | +[Here](example-page.md) is an example link to a relative path of a file (`example-page.md`) |
| 83 | +in the same directory, and from that page you can test linking to a subfoldr. |
| 84 | +In the case of not having a subfolder, we could write the link out directly: |
| 85 | + |
| 86 | +``` |
| 87 | +{% raw %}[example]({{ site.baseurl }}/docs/clusters/sherlock/getting-started.md){% endraw %} |
| 88 | +``` |
| 89 | + |
| 90 | +or better, there is a shortand trick! We can use the provided "includes" |
| 91 | +template to do the same based on the path to create a link: |
| 92 | + |
| 93 | +``` |
| 94 | +{% raw %}{% include doc.html name="Sherlock Cluster" path="clusters/sherlock/getting-started" %}{% endraw %} |
| 95 | +``` |
| 96 | +The path should be relative to the docs folder. |
| 97 | + |
| 98 | +#### Headers |
| 99 | + |
| 100 | +While this is a personal preference, it's recommended to create nesting |
| 101 | +of your docs via markdown sections in each of the files |
| 102 | +over creating more files. For example, take a look at the right |
| 103 | +side of this page, and you'll see a level represented for each header. |
| 104 | +This strategy means that we have fewer overall pages (easier to find content) |
| 105 | +that are still browsable easily via search or the table of contents on the right. |
| 106 | + |
| 107 | +### Pages |
| 108 | + |
| 109 | +The `pages` folder uses the same page layout, but is not part of the docs collection. |
| 110 | +The two are provided to create a distinction between website pages (e.g., about, |
| 111 | +feed.xml) and documentation pages. Whether you place your page under |
| 112 | +"pages" or "docs," for those pages that you want added to the navigation, |
| 113 | +you should add them to `_data/toc.yml`. If you've defined a `permalink` in the |
| 114 | +front end matter, you can use that (e.g., "About" below). If you haven't and |
| 115 | +want to link to docs, the url is the path starting with the docs folder. |
| 116 | + |
| 117 | +```yaml |
| 118 | + - title: "Getting Started" |
| 119 | + url: "/docs/getting-started/" |
| 120 | + - title: "About" |
| 121 | + url: "/about" |
| 122 | + - title: "News" |
| 123 | + url: "/news" |
| 124 | +``` |
| 125 | +
|
| 126 | +### News Posts |
| 127 | +
|
| 128 | +It might be the case that your site or group has news items that would |
| 129 | +warrent sharing with the community, and should be available as a feed. |
| 130 | +For this reason, you can write traditional [posts](https://jekyllrb.com/docs/posts/) in the `_posts` |
| 131 | +folder that will parse into the site [feed]({{ site.baseurl }}/feed.xml) |
| 132 | +The bottom of the page links the user to a post archive, where posts are organized |
| 133 | +according to the year. |
| 134 | + |
| 135 | +### Alerts |
| 136 | + |
| 137 | +{% include alert.html type="info" title="What is an alert?" content="An alert is a box that can stand out to indicate important information. You can choose from levels success, warning, danger, info, and primary. This example is an info box, and the code for it looks like this:" %} |
| 138 | + |
| 139 | +``` |
| 140 | +{%raw%}{% include alert.html type="info" title="What is an alert?" content="An alert is a box that can stand out to indicate important information. You can choose from levels success, warning, danger, info, and primary. This example is an info box, and the code for it looks like this:" %} |
| 141 | +{%endraw%} |
| 142 | +``` |
| 143 | +
|
| 144 | +Just for fun, here are all the types: |
| 145 | +
|
| 146 | +{% include alert.html type="warning" content="This is a warning" %} |
| 147 | +{% include alert.html type="danger" content="This alerts danger!" %} |
| 148 | +{% include alert.html type="success" content="This alerts success" %} |
| 149 | +
|
| 150 | +## Development |
| 151 | +
|
| 152 | +Initially (on OS X), you will need to setup [Brew](http://brew.sh/) which is a package manager for OS X and [Git](https://git-scm.com/). To install Brew and Git, run the following commands: |
| 153 | +
|
| 154 | +```bash |
| 155 | +/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" |
| 156 | +brew install git |
| 157 | +``` |
| 158 | + |
| 159 | +If you are on Debian/Ubuntu, then you can easily install git with `apt-get` |
| 160 | + |
| 161 | +```bash |
| 162 | +apt-get update && apt-get install -y git |
| 163 | +``` |
| 164 | + |
| 165 | +### Install Jekyll |
| 166 | + |
| 167 | +You can also install Jekyll with brew. |
| 168 | + |
| 169 | +```bash |
| 170 | +$ brew install ruby |
| 171 | +$ gem install jekyll |
| 172 | +$ gem install bundler |
| 173 | +$ bundle install |
| 174 | +``` |
| 175 | + |
| 176 | +On Ubuntu I do a different method: |
| 177 | + |
| 178 | +```bash |
| 179 | +git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build |
| 180 | +echo 'export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH"' >> ~/.bashrc |
| 181 | +exec $SHELL |
| 182 | +rbenv install 2.3.1 |
| 183 | +rbenv global 2.3.1 |
| 184 | +gem install bundler |
| 185 | +rbenv rehash |
| 186 | +ruby -v |
| 187 | + |
| 188 | +# Rails |
| 189 | +curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash - |
| 190 | +sudo apt-get install -y nodejs |
| 191 | +gem install rails -v 4.2.6 |
| 192 | +rbenv rehash |
| 193 | + |
| 194 | +# Jekyll |
| 195 | +gem install jekyll |
| 196 | +gem install github-pages |
| 197 | +gem install jekyll-sass-converter |
| 198 | + |
| 199 | +rbenv rehash |
| 200 | +``` |
| 201 | + |
| 202 | +### Get the code |
| 203 | + |
| 204 | +You should first fork the repository to your GitHub organization or username, |
| 205 | +and then clone it. |
| 206 | + |
| 207 | +```bash |
| 208 | +$ git clone https://github.com/<username</mkdocs-jekyll.git docs |
| 209 | +$ cd docs |
| 210 | +``` |
| 211 | + |
| 212 | +You can clone the repository right to where you want to host the docs: |
| 213 | + |
| 214 | +```bash |
| 215 | +$ git clone https://github.com/<username>/mkdocs-jekyll.git docs |
| 216 | +$ cd docs |
| 217 | +``` |
| 218 | + |
| 219 | + |
| 220 | +### Serve |
| 221 | + |
| 222 | +Depending on how you installed jekyll: |
| 223 | + |
| 224 | +```bash |
| 225 | +jekyll serve |
| 226 | +# or |
| 227 | +bundle exec jekyll serve |
| 228 | +``` |
| 229 | + |
| 230 | +You can then move on to customization. |
| 231 | + |
| 232 | +## Customization |
| 233 | + |
| 234 | +#### config.yml |
| 235 | + |
| 236 | +To edit configuration values, customize the [_config.yml](_config.yml). |
| 237 | +Most are documented there, and please [open an issue](https://www.github.com/{{ site.github_user }}/{{ site.github_user }}/issues) if you have questions. |
| 238 | + |
| 239 | +#### Adding pages |
| 240 | + |
| 241 | +To add pages, write them into the [pages](pages) folder. |
| 242 | +You define urls based on the `permalink` attribute in your pages, |
| 243 | +and then add them to the navigation by adding to the content of [_data/toc.yml](_data/toc.yml). |
| 244 | + |
| 245 | +#### Tags |
| 246 | + |
| 247 | +If you include tags on a page, by default they won't link to anything. However, |
| 248 | +if you define a `tag_search_endpoint` url in your configuration file, by clicking |
| 249 | +the tag, the user will be taken to this page to search for it. As an example, |
| 250 | +we define the current search endpoint to be Ask Cyberinfrastructure, and |
| 251 | +page tags link to a search on it: |
| 252 | + |
| 253 | +``` |
| 254 | +tag_search_endpoint: https://ask.cyberinfrastructure.org/search?q= |
| 255 | +``` |
| 256 | + |
| 257 | +The tags appear at the bottom of the page for you to click, as on this page. |
0 commit comments