-
Notifications
You must be signed in to change notification settings - Fork 1
/
Hakyll-Fresh-Installation.html
174 lines (162 loc) · 14.3 KB
/
Hakyll-Fresh-Installation.html
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="icon" type="image/png" href="./images/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="./images/favicon-16x16.png" sizes="16x16" />
<title>How to install and use Hakyll - SPK's Rationality Essays</title>
<link rel="stylesheet" type="text/css" href="./css/default.css" />
<link rel="stylesheet" type="text/css" href="./css/highlight.css" />
<!-- <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script> -->
<!-- <script type="text/javascript" src="/js/header-links.js"></script> -->
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link href="atom.xml" type="application/atom+xml" rel="alternate" title="Sitewide ATOM/RSS Feed" />
<!-- Google Analytics stuff -->
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-DEWF2J5BG8"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-DEWF2J5BG8');
</script>
<script type="text/javascript" src="https://fast.fonts.net/jsapi/f7f47a40-b25b-44ee-9f9c-cfdfc8bb2741.js"></script>
</head>
<body>
<div id="header">
<div id="logo">
<a href="./">SPK's Rationality Essays</a>
</div>
<div id="navigation">
<a href="./">Home</a>
<a href="./notes.html">Notes</a>
<!-- <a href="/about.html">About</a> -->
<a href="./archive.html">Archive</a>
<a href="./atom.xml" type="application/atom+xml" rel="alternate" title="Sitewide ATOM/RSS Feed">RSS</a>
</div>
</div>
<div id="content">
<h1 id="post-title">How to install and use Hakyll</h1>
<!-- <center><img src="https://fbcdn-sphotos-d-a.akamaihd.net/hphotos-ak-prn1/t31.0-8/p600x600/10257116_10202295769100492_2438594605053717342_o.jpg" height="400" width="300" class="sujeet-pic" alt="Sujeet pic" /></center> -->
<p><strong>Note</strong>: This is a Hakyll usage guide aimed at people completely new to Linux.</p>
<h1 id="what-is-hakyll">What is Hakyll?</h1>
<p><a href>Hakyll</a> lets you generate a static site. For now, you can think of it as something that converts your <a href>Markdown</a> files into HTML. When you put your HTML files on some web-hosting site, other people can view them from their browsers.</p>
<p>This is different from dynamic sites like <a href>WordPress</a>, where you don’t have access to the actual HTML or Markdown files for your own website. You have to write stuff in some online editor and WordPress updates everything magically. You can only do what WordPress allows you to - you don’t have full control over your website.</p>
<h1 id="how-does-hakyll-work">How does Hakyll work?</h1>
<p>You write each blog post in a separate Markdown file. You use Hakyll’s instant preview ability to see how your website looks at each point. You add how many ever posts you want, in whatever order you want. You do all of this offline. When you’re happy with your changes, you upload the Hakyll-generated HTML files to some web-hosting site.</p>
<p>In short, you write Markdown; Hakyll turns it to HTML; and you send the HTML to some website. You only need a web connection for the final step.</p>
<p>Also, we use a time-machine program called <code>git</code> to save and send the HTML. This way, if we break something or lose our local copy or just screw it up in any way, we can go back in time to a version of the website that looked fine. <a href>Github</a> is a free site that will let you put up time-machined HTML pages.</p>
<h1 id="overview">Overview</h1>
<p>Let’s take this one baby step at a time instead of trying to get the whole thing going in one shot.</p>
<p>First, we install everything needed for Hakyll. Then, we set up a basic site for the first time and view it in our browser. Next, we learn how to make changes locally and view the updated website. Finally, we learn how to upload our website to Github so that everyone can view it.</p>
<h1 id="installation">Installation</h1>
<p>To install ghc, simply install <code>haskell-platform</code></p>
<p>Haskell is a programming language, like C, C++, or Java.</p>
<pre><code>$ sudo apt-get install haskell-platform</code></pre>
<p>I’m assuming you already have the <code>git</code> package. Still,</p>
<pre><code>$ sudo apt-get install git</code></pre>
<p>Install <code>hakyll</code> using <code>cabal</code></p>
<p>First, install cabal.</p>
<pre><code>$ sudo apt-get install cabal-install</code></pre>
<p>Then, install hakyll</p>
<pre><code>$ cabal install hakyll</code></pre>
<p>If you’ve come so far, pat yourself on the back. You’re almost there.</p>
<h2 id="finding-hakyll-init">Finding hakyll-init</h2>
<p>First, you need to make sure the terminal can find <code>hakyll-init</code>. It can only do that if the directory containing the <code>hakyll-init</code> program is in the PATH variable. So, let’s put it in the PATH.</p>
<p><code>hakyll-init</code> is found in the directory called <code>~/.cabal/bin</code>. So, we need to add <code>~/.cabal/bin</code> to the PATH.</p>
<p>Put the following line at the end of the file called <code>~/.bashrc</code></p>
<pre><code>$ export PATH=~/.cabal/bin:$PATH</code></pre>
<p>If there is no such file in the home directory (which is called ~), then create one - using Gedit, maybe. After you have saved that file, run</p>
<pre><code>$ source ~/.bashrc</code></pre>
<p>in the terminal. (Or just restart the terminal)</p>
<hr />
<h1 id="setting-up-your-site-for-the-first-time">Setting up your site for the first time</h1>
<p>Now, let’s create a basic site.</p>
<p>Decide where you want to put your website files. Let’s say you have created a <code>~/Website</code> directory. Go there (using the command <code>cd</code>)</p>
<pre><code>$ cd ~/Website</code></pre>
<p>The terminal prompt should show that you are in the <code>~/Website</code> directory.</p>
<p>Now, create a basic site:</p>
<pre><code>$ hakyll-init my-site</code></pre>
<p>You’ll now have a new directory called <code>my-site</code> with default configurations.</p>
<h2 id="create-the-site-generator">Create the site generator</h2>
<p>Let’s start adding lots of changes to the website and make it perfect within 5 minutes.</p>
<p>No.</p>
<p>Let’s first test it as it is. Test first, then make changes.</p>
<p>We need a program that will turn your Markdown files to HTML That is called the <code>site</code> program.</p>
<p>Go into the <code>my-site</code> directory (using <code>cd</code>, as usual)</p>
<pre><code>$ cd my-site</code></pre>
<p>The <code>site.hs</code> file in this directory contains the configuration for your website (check it out). By compiling it, you get a <code>site</code> program that you can use to build your website.</p>
<p>Compile the <code>site.hs</code> configuration file:</p>
<pre><code>$ ghc --make -threaded site.hs</code></pre>
<p>You need to do this every time you make a change to the configuration, which you will do quite rarely.</p>
<h2 id="build-your-website">Build your website</h2>
<p>You haven’t added anything yet, but let’s just see what the default website looks like. Tell the <code>site</code> program to build your website.</p>
<pre><code>$ ./site build</code></pre>
<p>You should now be able to see a directory called <code>_site</code>. It will contain HTML files, CSS files, etc. This is your website.</p>
<p>Let’s view your website in the browser. First, you need to tell the <code>site</code> program to run a preview server.</p>
<pre><code>$ ./site watch</code></pre>
<p>This will let you to view your pages in the browser. Open <a href="http://localhost:8000/" class="uri">http://localhost:8000/</a> in Firefox or Chrome or whatever. There you go! You now have a working local website.</p>
<h1 id="everyday-usage">Everyday usage</h1>
<p>To change an existing Markdown page, just go into one of the pre-existing Markdown pages (using Gedit or some other editor). Make your changes. If <code>./site watch</code> is running, you will be able to see the changes in your website by refreshing your browser page. You can change different parts, like the title, etc. and watch the website getting updated.</p>
<p>To add a new page, just create a new file. Let’s say you want to create <code>Foo.markdown</code>. Just copy an existing page (so that you get the formatting and initial details like title, etc.) and rename it to <code>Foo.markdown</code>. Check the website in your browser. If you can’t see the new page in your browser, then you may have to restart the preview server. Stop it by pressing <code>C-c C-c</code>. Then, run <code>./site watch</code> again.</p>
<h1 id="coming-soon">Coming Soon</h1>
<p>How to set up a Github repository for your website; how to get your website ready to be uploaded; how to actually upload it so that everybody can view it online.</p>
<h1 id="notes">Notes</h1>
<p>Thanks to the official Hakyll <a href="http://jaspervdj.be/hakyll/tutorials/01-installation.html">installation page</a>. I expanded each step so that my non-programmer friend could use Hakyll to create a personal static site.</p>
<h2 id="faq">FAQ</h2>
<ul>
<li><p>I don’t have an idea what am doing. I just do as is given in some website that I come across.</p>
<p>Check if the above instructions have given you a good idea of what you’re doing.</p>
<p>How do you know if they have given you a good idea? Well, do you have a working website at the end of the day? Do you know what you need to do to add new pages, change existing ones, upload your website, etc.? Then, it means you have got a good idea.</p></li>
<li><p>I don’t know how to know if the installation has been performed correctly.</p>
<blockquote>
<p>How do we check our installation, Master Wayne?</p>
<p>We test the program immediately, before making any changes.</p>
</blockquote>
<p>First of all, if you had some errors while installing the program, <code>apt-get</code> will tell you right away - “<code>ERROR: something something something</code>”. If it worked correctly, it will just stay silent. That is part of the Unix philosophy (Linux is an open-source version of Unix).</p>
<blockquote>
<p>Rule of Silence: When a program has nothing surprising to say, it should say nothing.</p>
<p>One of Unix’s oldest and most persistent design rules is that when a program has nothing interesting or surprising to say, it should shut up. Well-behaved Unix programs do their jobs unobtrusively, with a minimum of fuss and bother. Silence is golden.</p>
<p>– Eric S. Raymond, <a href>The Art of Unix Programming</a></p>
</blockquote>
<p>Just to convince yourself, try running the program. Say you installed <code>git</code>. Now, go to the terminal and say <code>git</code> or <code>git --help</code>. If you haven’t installed the program right, you’ll get a message saying “command not found”. If you have installed it right, then you will get some basic help messages.</p></li>
<li><p>I don’t know what is the difference between package, software. Is cabal a package, is git a software? Basics of types of things encountered while using UBUNTU.</p>
<p>Roughly, software is what you can run, like Firefox. Package is like the… um… package or box that the software comes in. People use both of them interchangeably.</p>
<p>Most of the time, if you want to use some software (aka program) called <code>foo</code>, you need to install it by using <code>sudo apt-get install foo</code>. That’s it. Even easier, you can use the Ubuntu Software Center for popular programs.</p>
<p>Further notes:</p>
<p>Theoretically, you need to download the package and then unpack it and install the software. <code>apt-get install</code> does both things without telling you.</p>
<p>So, when you say <code>sudo apt-get install git</code>, <code>git</code> is the name of the package. Now, <code>apt-get</code> will unpack and install the software. Fortunately, like in most cases, the program is called <code>git</code> too. So, you can use <code>git</code> to run the software.</p></li>
<li><p>You say it takes a day to get hakyll done. What does that mean. How about you say it in terms of hours.</p>
<p>It will take a day for you, as a new user. In terms of hours, that’s like 24 hours, depending on the relative position of the Sun and the Earth. It’s just like setting up Ubuntu for the first time, which can take a while.</p></li>
<li><p>How much of Cabal and Hakyll and git basics do I need to know to set up this page.</p>
<p>Basically, just what I wrote in the above tutorial. A bit of <code>git</code>, and almost nothing of <code>cabal</code> or <code>hakyll</code>.</p></li>
</ul>
<div class="info">Created: September 1, 2015</div>
<div class="info">Last modified: January 25, 2016</div>
<div class="info">Status: in-progress</div>
<div class="info"><b>Tags</b>: hakyll</div>
<br />
<div id="disqus_thread"></div>
<script type="text/javascript">
/* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
var disqus_shortname = 'spkrationalitytrainingground'; // required: replace example with your forum shortname
var disqus_identifier = '/Hakyll-Fresh-Installation.html';
var disqus_title = 'How to install and use Hakyll';
/* * * DON'T EDIT BELOW THIS LINE * * */
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<script type="text/javascript" src="https://fast.fonts.net/jsapi/f7f47a40-b25b-44ee-9f9c-cfdfc8bb2741.js"></script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div>
<div id="footer">
Site proudly generated by
<a href="http://jaspervdj.be/hakyll">Hakyll</a>
</div>
</body>
</html>