index.html 18.7 KB
Newer Older
Jonathan Carter's avatar
Jonathan Carter committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
<!DOCTYPE html>
  
  
  
  
   <html class="no-js"> 

  <head lang="en-us">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,user-scalable=no,initial-scale=1,maximum-scale=1">
    <meta http-equiv="X-UA-Compatible" content="IE=10" />
    <title>Getting started - AIMS Desktop</title>
    <meta name="generator" content="Hugo 0.18.1" />

    
    <link rel="canonical" href="https://desktop.aims.ac.za/getting-started/">
    

    <meta property="og:url" content="https://desktop.aims.ac.za/getting-started/">
    <meta property="og:title" content="AIMS Desktop">
    <meta property="og:image" content="https://desktop.aims.ac.za/images/logo.png">
    <meta name="apple-mobile-web-app-title" content="AIMS Desktop">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

    <link rel="shortcut icon" type="image/x-icon" href="https://desktop.aims.ac.za/images/favicon.ico">
    <link rel="icon" type="image/x-icon" href="https://desktop.aims.ac.za/images/favicon.ico">

    <style>
      @font-face {
        font-family: 'Icon';
        src: url('https://desktop.aims.ac.za/fonts/icon.eot');
        src: url('https://desktop.aims.ac.za/fonts/icon.eot')
               format('embedded-opentype'),
             url('https://desktop.aims.ac.za/fonts/icon.woff')
               format('woff'),
             url('https://desktop.aims.ac.za/fonts/icon.ttf')
               format('truetype'),
             url('https://desktop.aims.ac.za/fonts/icon.svg')
               format('svg');
        font-weight: normal;
        font-style: normal;
      }
    </style>

    <link rel="stylesheet" href="https://desktop.aims.ac.za/stylesheets/application.css">
    <link rel="stylesheet" href="https://desktop.aims.ac.za/stylesheets/temporary.css">
    <link rel="stylesheet" href="https://desktop.aims.ac.za/stylesheets/palettes.css">
    <link rel="stylesheet" href="https://desktop.aims.ac.za/stylesheets/highlight/highlight.css">

    
    
    
    <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Ubuntu:400,700|Ubuntu&#43;Mono">
    <style>
      body, input {
        font-family: 'Ubuntu', Helvetica, Arial, sans-serif;
      }
      pre, code {
        font-family: 'Ubuntu Mono', 'Courier New', 'Courier', monospace;
      }
    </style>

    
    <script src="https://desktop.aims.ac.za/javascripts/modernizr.js"></script>

    

  </head>
Jonathan Carter's avatar
Jonathan Carter committed
70
  <body class="palette-primary-#fc0000 palette-accent-blue">
Jonathan Carter's avatar
Jonathan Carter committed
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92




<div class="backdrop">
	<div class="backdrop-paper"></div>
</div>

<input class="toggle" type="checkbox" id="toggle-drawer">
<input class="toggle" type="checkbox" id="toggle-search">
<label class="toggle-button overlay" for="toggle-drawer"></label>

<header class="header">
	<nav aria-label="Header">
  <div class="bar default">
    <div class="button button-menu" role="button" aria-label="Menu">
      <label class="toggle-button icon icon-menu" for="toggle-drawer">
        <span></span>
      </label>
    </div>
    <div class="stretch">
      <div class="title">
Jonathan Carter's avatar
Jonathan Carter committed
93
94
        
	<a href="https://desktop.aims.ac.za/"><img alt="AIMS Desktop" src="https://desktop.aims.ac.za/images/aims-desktop-heading.png" /></a>
Jonathan Carter's avatar
Jonathan Carter committed
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
      </div>
    </div>

    

    
    
        
  </div>
  <div class="bar search">
    <div class="button button-close" role="button" aria-label="Close">
      <label class="toggle-button icon icon-back" for="toggle-search"></label>
    </div>
    <div class="stretch">
      <div class="field">
        <input class="query" type="text" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck>
      </div>
    </div>
    <div class="button button-reset" role="button" aria-label="Search">
      <button class="toggle-button icon icon-close" id="reset-search"></button>
    </div>
  </div>
</nav>
Jonathan Carter's avatar
Jonathan Carter committed
118

Jonathan Carter's avatar
Jonathan Carter committed
119
120
121
122
123
</header>

<main class="main">
	<div class="drawer">
		<nav aria-label="Navigation">
Jonathan Carter's avatar
Jonathan Carter committed
124
  <a href="https://desktop.aims.ac.za/download" class="project">
Jonathan Carter's avatar
Jonathan Carter committed
125
126
127
128
129
130
131
    <div class="banner">
      
        <div class="logo">
          <img src="https://desktop.aims.ac.za/images/logo.png">
        </div>
      
      <div class="name">
Jonathan Carter's avatar
Jonathan Carter committed
132
        <strong>AIMS Desktop <span class="version">2017.1</span></strong>
Jonathan Carter's avatar
Jonathan Carter committed
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
        
      </div>
    </div>
  </a>

  <div class="scrollable">
    <div class="wrapper">
      

      <div class="toc">
        
        <ul>
          




<li>
  
    



Jonathan Carter's avatar
Jonathan Carter committed
156
<a  title="AIMS Desktop" href="https://desktop.aims.ac.za/">
Jonathan Carter's avatar
Jonathan Carter committed
157
	
Jonathan Carter's avatar
Jonathan Carter committed
158
	AIMS Desktop
Jonathan Carter's avatar
Jonathan Carter committed
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
</a>



  
</li>



<li>
  
    



<a class="current" title="Getting started" href="https://desktop.aims.ac.za/getting-started/">
	
	Getting started
</a>


<ul id="scrollspy">
</ul>


  
</li>



<li>
  
    



Jonathan Carter's avatar
Jonathan Carter committed
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
<a  title="Configuration Guide" href="https://desktop.aims.ac.za/configuration/">
	
	Configuration Guide
</a>



  
</li>



<li>
  
    



<a  title="Troubleshooting" href="https://desktop.aims.ac.za/troubleshooting/">
Jonathan Carter's avatar
Jonathan Carter committed
214
	
Jonathan Carter's avatar
Jonathan Carter committed
215
	Troubleshooting
Jonathan Carter's avatar
Jonathan Carter committed
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
</a>



  
</li>



<li>
  
    



<a  title="Roadmap" href="https://desktop.aims.ac.za/roadmap/">
	
	Roadmap
</a>



  
</li>



<li>
  
    



<a  title="License" href="https://desktop.aims.ac.za/license/">
	
	License
</a>



  
</li>



Jonathan Carter's avatar
Jonathan Carter committed
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
<li>
  
    



<a  title="Donate" href="https://desktop.aims.ac.za/donate/">
	
	Donate
</a>



  
</li>
Jonathan Carter's avatar
Jonathan Carter committed
276
277
278
279


        </ul>
        
Jonathan Carter's avatar
Jonathan Carter committed
280
281

        
Jonathan Carter's avatar
Jonathan Carter committed
282
283
284
285
286
287
288
289
290
291
292
293
294
      </div>
    </div>
  </div>
</nav>

	</div>

	<article class="article">
		<div class="wrapper">
			<h1>Getting started </h1>

			

Jonathan Carter's avatar
Jonathan Carter committed
295
296
<h2 id="download-aims-desktop">Download AIMS Desktop</h2>

Jonathan Carter's avatar
Jonathan Carter committed
297
298
<h2 id="installation">Installation</h2>

Jonathan Carter's avatar
Jonathan Carter committed
299
<h3 id="installing-aims-desktop">Installing AIMS Desktop</h3>
Jonathan Carter's avatar
Jonathan Carter committed
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532

<p>Hugo itself is just a single binary without dependencies on expensive runtimes like Ruby, Python or PHP and without dependencies on any databases. You just need to download the <a href="https://github.com/spf13/hugo/releases">latest version</a>. For more information read the official <a href="http://gohugo.io/overview/installing/">installation guides</a>.</p>

<p>Let&rsquo;s make sure Hugo is set up as expected. You should see a similar version number in your terminal:</p>

<pre><code class="language-sh">hugo version
# Hugo Static Site Generator v0.15 BuildDate: 2016-01-03T12:47:47+01:00
</code></pre>

<h3 id="installing-material">Installing Material</h3>

<p>Next, assuming you have Hugo up and running the <code>hugo-material-docs</code> theme can be installed with <code>git</code>:</p>

<pre><code class="language-sh"># create a new Hugo website
hugo new site my-awesome-docs

# move into the themes folder of your website
cd my-awesome-docs/themes/

# download the theme
git clone git@github.com:digitalcraftsman/hugo-material-docs.git
</code></pre>

<h2 id="setup">Setup</h2>

<p>Next, take a look in the <code>exampleSite</code> folder at <code>themes/hugo-material-docs/</code>. This directory contains an example config file and the content that you are currently reading. It serves as an example setup for your documentation.</p>

<p>Copy at least the <code>config.toml</code> in the root directory of your website. Overwrite the existing config file if necessary.</p>

<p>Hugo includes a development server, so you can view your changes as you go -
very handy. Spin it up with the following command:</p>

<pre><code class="language-sh">hugo server
</code></pre>

<p>Now you can go to <a href="http://localhost:1313">localhost:1313</a> and the Material
theme should be visible. You can now start writing your documentation, or read
on and customize the theme through some options.</p>

<h2 id="configuration">Configuration</h2>

<p>Before you are able to deploy your documentation you should take a few minute to adjust some information in the <code>config.toml</code>. Open the file in an editor:</p>

<pre><code class="language-toml">baseurl = &quot;https://example.com/&quot;
languageCode = &quot;en-us&quot;
title = &quot;Material Docs&quot;

[params]
  # General information
  author = &quot;Digitalcraftsman&quot;
  description = &quot;A material design theme for documentations.&quot;
  copyright = &quot;Released under the MIT license&quot;
</code></pre>

<h2 id="options">Options</h2>

<h3 id="github-integration">Github integration</h3>

<p>If your project is hosted on GitHub, add the repository link to the
configuration. If the <code>provider</code> equals <strong>GitHub</strong>, the Material theme will
add a download and star button, and display the number of stars:</p>

<pre><code class="language-toml">[params]
  # Repository
  provider = &quot;GitHub&quot;
  repo_url = &quot;https://github.com/digitalcraftsman/hugo-material-docs&quot;
</code></pre>

<h3 id="adding-a-version">Adding a version</h3>

<p>In order to add the current version next to the project banner inside the
drawer, you can set the variable <code>version</code>:</p>

<pre><code class="language-toml">[params]
  version = &quot;1.0.0&quot;
</code></pre>

<p>This will also change the link behind the download button to point to the
archive with the respective version on GitHub, assuming a release tagged with
this exact version identifier.</p>

<h3 id="adding-a-logo">Adding a logo</h3>

<p>If your project has a logo, you can add it to the drawer/navigation by defining
the variable <code>logo</code>. Ideally, the image of your logo should have
rectangular shape with a minimum resolution of 128x128 and leave some room
towards the edges. The logo will also be used as a web application icon on iOS.
Either save your logo somewhere in the <code>static/</code> folder and reference the file relative to this location or use an external URL:</p>

<pre><code class="language-toml">[params]
  logo = &quot;images/logo.png&quot;
</code></pre>

<h3 id="adding-a-custom-favicon">Adding a custom favicon</h3>

<p>Favicons are small small icons that are displayed in the tabs right next to the title of the current page. As with the logo above you need to save your favicon in <code>static/</code> and link it relative to this folder or use an external URL:</p>

<pre><code class="language-toml">[params]
  favicon = &quot;favicon.ico&quot;
</code></pre>

<h3 id="google-analytics">Google Analytics</h3>

<p>You can enable Google Analytics by replacing <code>UA-XXXXXXXX-X</code> with your own tracking code.</p>

<pre><code class="language-toml">googleAnalytics = &quot;UA-XXXXXXXX-X&quot;
</code></pre>

<h3 id="small-tweaks">Small tweaks</h3>

<p>This theme provides a simple way for making small adjustments, that is changing
some margins, centering text, etc. The <code>custom_css</code> and <code>custom_js</code> option allow you to add further CSS and JS files. They can either reside locally in the <code>/static</code> folder or on an external server, e.g. a CDN. In both cases use either the relative path to <code>/static</code> or the absolute URL to the external ressource.</p>

<pre><code class="language-toml">[params]
  # Custom assets
  custom_css = [
    &quot;foo.css&quot;,
    &quot;bar.css&quot;
  ]

  custom_js  = [&quot;buzz.js&quot;]
</code></pre>

<h3 id="changing-the-color-palette">Changing the color palette</h3>

<p>Material defines a default hue for every primary and accent color on Google&rsquo;s
material design [color palette][]. This makes it very easy to change the overall look of the theme. Just set the variables <code>palette.primary</code> and <code>palette.accent</code> to one of the colors defined in the palette:</p>

<pre><code class="language-toml">[params.palette]
  primary = &quot;red&quot;
  accent  = &quot;light-green&quot;
</code></pre>

<p>Color names can be written upper- or lowercase but must match the names of the
material design <a href="http://www.materialui.co/colors">color palette</a>. Valid values are: <em>red</em>, <em>pink</em>, <em>purple</em>, <em>deep purple</em>, <em>indigo</em>, <em>blue</em>, <em>light-blue</em>, <em>cyan</em>, <em>teal</em>, <em>green</em>, <em>light-green</em>,
<em>lime</em>, <em>yellow</em>, <em>amber</em>, <em>orange</em>, <em>deep-orange</em>, <em>brown</em>, <em>grey</em> and
<em>blue-grey</em>. The last three colors can only be used as a primary color.</p>

<p><img src="https://desktop.aims.ac.za/images/colors.png" alt="Color palette" /></p>

<p>If the color is set via this configuration, an additional CSS file called
<code>palettes.css</code> is included that defines the color palettes.</p>

<h3 id="changing-the-font-family">Changing the font family</h3>

<p>Material uses the <a href="http://font.ubuntu.com">Ubuntu font family</a> by default, specifically the regular sans-serif type for text and the monospaced type for code. Both fonts are loaded from <a href="https://www.google.com/fonts">Google Fonts</a> and can be easily changed to other fonts, like for example Google&rsquo;s own <a href="https://www.google.com/fonts/specimen/Roboto">Roboto font</a>:</p>

<pre><code class="language-toml">[params.font]
  text = &quot;Roboto&quot;
  code = &quot;Roboto Mono&quot;
</code></pre>

<p>The text font will be loaded in font-weights 400 and <strong>700</strong>, the monospaced
font in regular weight.</p>

<h3 id="syntax-highlighting">Syntax highlighting</h3>

<p>This theme uses the popular <a href="https://highlightjs.org/">Highlight.js</a> library to colorize code examples. The default theme is called <code>Github</code> with a few small tweaks. You can link our own theme if you like. Again, store your stylesheet in the <code>static/</code> folder and set the relative path in the config file:</p>

<pre><code class="language-toml">[params]
  # Syntax highlighting theme
  highlight_css  = &quot;path/to/theme.css&quot;
</code></pre>

<h3 id="adding-a-github-and-twitter-account">Adding a GitHub and Twitter account</h3>

<p>If you have a GitHub and/or Twitter account, you can add links to your
accounts to the drawer by setting the variables <code>github</code> and
<code>twitter</code> respectively:</p>

<pre><code class="language-toml">[social]
  twitter = &quot;&quot;
  github  = &quot;digitalcraftsman&quot;
</code></pre>

<h3 id="adding-menu-entries">Adding menu entries</h3>

<p>Once you created your first content files you can link them manually in the sidebar on the left. A menu entry has the following schema:</p>

<pre><code class="language-toml">[[menu.main]]
  name   = &quot;Material&quot;
  url    = &quot;/&quot;
  weight = 0
  pre    = &quot;&quot;
</code></pre>

<p><code>name</code> is the title displayed in the menu and <code>url</code> the relative URL to the content. The <code>weight</code> attribute allows you to modify the order of the menu entries. A menu entry appears further down the more weight you add. The <code>pre</code> attribute is optional and allows you to *pre*pend elements to a menu link, e.g. an icon.</p>

<p>Instead of just linking a single file you can enhance the sidebar by creating a nested menu. This way you can list all pages of a section instead of linking them one by one (without nesting).</p>

<p>You need extend the frontmatter of each file content file in a section slightly. The snippet below registers this content file as &lsquo;child&rsquo; of a menu entry that already exists.</p>

<pre><code class="language-yaml">menu:
  main:
    parent: Material
    identifier: &lt;link name&gt;
    weight: 0
</code></pre>

<p><code>main</code> specifies to which menu the content file should be added. <code>main</code> is the only menu in this theme by default. <code>parent</code> let&rsquo;s you register this content file to an existing menu entry, in this case the <code>Material</code> link. Note that the parent in the frontmatter needs to match the name in <code>config.toml</code>.</p>

<p><code>identifier</code> is the link that is shown in the menu. Ideally you choose the same name for the <code>identifier</code> and the <code>title</code> of the page. Again, <code>weight</code> allows you to change the order of the nested links in a section.</p>

<h3 id="markdown-extensions">Markdown extensions</h3>

<p>Hugo uses <a href="https://github.com/russross/blackfriday">Blackfriday</a> to process your content. For a detailed description of all options take a look at the <a href="http://gohugo.io/overview/configuration/#configure-blackfriday-rendering">Blackfriday configuration</a> section in the Hugo documentation.</p>

<pre><code class="language-toml">[blackfriday]
  smartypants = true
  fractions = true
  smartDashes = true
  plainIDAnchors = true
</code></pre>


			<aside class="copyright" role="note">
				
				Documentation built with
				<a href="https://www.gohugo.io" target="_blank">Hugo</a>
				using the
				<a href="http://github.com/digitalcraftsman/hugo-material-docs" target="_blank">Material</a> theme.
			</aside>

			<footer class="footer">
				

<nav class="pagination" aria-label="Footer">
  <div class="previous">
  
  </div>

  <div class="next">
  
Jonathan Carter's avatar
Jonathan Carter committed
533
      <a href="https://desktop.aims.ac.za/configuration/" title="Adding content">
Jonathan Carter's avatar
Jonathan Carter committed
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
        <span class="direction">
          Next
        </span>
        <div class="page">
          <div class="stretch">
            <div class="title">
              Adding content
            </div>
          </div>
          <div class="button button-next" role="button" aria-label="Next">
            <i class="icon icon-forward"></i>
          </div>
        </div>
      </a>
  
  </div>
</nav>





			</footer>
		</div>
	</article>

	<div class="results" role="status" aria-live="polite">
		<div class="scrollable">
			<div class="wrapper">
				<div class="meta"></div>
				<div class="list"></div>
			</div>
		</div>
	</div>
</main>

    <script>
    
Jonathan Carter's avatar
Jonathan Carter committed
572
573
      var base_url = '';
      var repo_id  = '';
Jonathan Carter's avatar
Jonathan Carter committed
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
    
    </script>

    <script src="https://desktop.aims.ac.za/javascripts/application.js"></script>
    

    <script>
      /* Add headers to scrollspy */
      var headers   = document.getElementsByTagName("h2");
      var scrollspy = document.getElementById('scrollspy');

      if(scrollspy) {
        if(headers.length > 0) {
          for(var i = 0; i < headers.length; i++) {
            var li = document.createElement("li");
            li.setAttribute("class", "anchor");

            var a  = document.createElement("a");
            a.setAttribute("href", "#" + headers[i].id);
            a.setAttribute("title", headers[i].innerHTML);
            a.innerHTML = headers[i].innerHTML;

            li.appendChild(a)
            scrollspy.appendChild(li);
          }
        } else {
          scrollspy.parentElement.removeChild(scrollspy)
        }


        /* Add permanent link next to the headers */
        var headers = document.querySelectorAll("h1, h2, h3, h4, h5, h6");

        for(var i = 0; i < headers.length; i++) {
            var a = document.createElement("a");
            a.setAttribute("class", "headerlink");
            a.setAttribute("href", "#" + headers[i].id);
            a.setAttribute("title", "Permanent link")
            a.innerHTML = "#";
            headers[i].appendChild(a);
        }
      }
    </script>

    

    <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.8.0/highlight.min.js"></script>
    <script>hljs.initHighlightingOnLoad();</script>
  </body>
</html>