Merge pull request #20 from GemCopeland/eleventy

Eleventy

.eleventy.js

@@ -0,0 +1,5 @@
+module.exports = function(eleventyConfig) {
+  eleventyConfig.setBrowserSyncConfig({
+    notify: true
+  });
+};

.gitignore

@@ -0,0 +1,2 @@
+_site/
+node_modules/

README.md

@@ -1,13 +1,6 @@
 # personal-website
-This is a simple website for publishing a CV, research and writing. It will be used for [gemmacope.land](gemmacope.land).
-
-## Description
-
-This website is a collaboration between Gemma Copeland and Piper Haywood.
 
-In the interest of being as transparent and open about our process as possible, we're documenting everything in this README from the beginning.
-
-Below is an outline of our thinking process so far. It's probably not of interest to anyone but us!
+This is a simple website for publishing a CV, research and writing. It will be used for [gemmacope.land](gemmacope.land).
 
 ## Rationale
 
@@ -18,64 +11,76 @@ Below is an outline of our thinking process so far. It's probably not of interes
 - To allow other people with similar interests and levels of experience to fork it
 - To be open about our process from the beginning
 
-## Index
+## Guide
+
+The instructions below assume that the reader is an enthusiastic beginner to things like Git, the command line, static site generators, and other things code-related. As such, there are footnotes peppered throughout that provide a little more context on terms that may be unfamiliar.
+
+### Getting started
+
+We’re using Git for version control and GitHub as a remote repository host<sup id="ref-1"><a href="#footnote-1">1</a></sup>. Because of this, our first task is to <mark>create a local copy of the repository</mark> (repo) on your computer. Open up the command line<sup id="ref-2"><a href="#footnote-2">2</a></sup> and then use the command `cd`<sup id="ref-3"><a href="#footnote-3">3</a></sup> to navigate to the folder where you’d like to store these website files. Next, clone this repo by running `git clone https://github.com/GemCopeland/personal-website.git personal-website`<sup id="ref-4"><a href="#footnote-4">4</a></sup>. Once this command finishes executing, you should have all of the files set up in the directory you specified at the end of your `git clone` command. This includes the `/.git`<sup id="ref-5"><a href="#footnote-5">5</a></sup> files that are helping us with version control.
+
+Next, we need to <mark>install the dependencies</mark> using `npm`<sup id="ref-6"><a href="#footnote-6">6</a></sup>. One of the core dependencies for this project is [Eleventy](https://www.11ty.io/), a static site generator<sup id="ref-7"><a href="#footnote-7">7</a></sup>. Check that you have `npm` installed globally<sup id="ref-8"><a href="#footnote-8">8</a></sup> by running `npm -v`, and check that you have at least version 8 of Node.js by running `node -v`. If you get an error with either command, you probably need to install Node.js and / or `npm`. Visit [npmjs.com](https://www.npmjs.com/get-npm) to get what you need. If your version of Node.js is too old, you’ll need to update it<sup id="ref-9"><a href="#footnote-9">9</a></sup>. If `npm` and `node` are looking good, you can go ahead and install this project’s dependencies by running `npm install`.
+
+At this point, we’ve got the static site generator [Eleventy](https://www.11ty.io/) ready for use. Run `npx @11ty/eleventy --serve` to <mark>fire up a local web server</mark>. You’ll see a bunch of output related to writing, processing, and watching files. Once the output shows the BrowserSync<sup id="ref-10"><a href="#footnote-10">10</a></sup> Access URLs, visit `http://localhost:8080/` in your preferred browser. You should see your site! To shut down your local web server, type in the command `ctrl + c` (it looks like `^C` in the CLI).
+
+### Deploying your site
 
-We have two options for this, either having a number of freeform text fields or going down a more structured data route. We agreed that we prefer the more structured data route, as this will also become an archive over time.
+To deploy the website to a more traditional web host via FTP / SFTP<sup id="ref-11"><a href="#footnote-11">11</a></sup>, compile the website by running `npx @11ty/eleventy`. This will put all of your website files in to the output folder `/_site`, the Eleventy default.
 
-Items will automatically move from _Current and Upcoming_ to _Previous_ based on their date range
+Alternatively, <mark>hook the repo up to Netlify</mark>. [Here’s a step-by-step guide](https://www.netlify.com/blog/2016/09/29/a-step-by-step-guide-deploying-on-netlify/). These are the settings you’d use:
 
-We considered how to differentiate between short-term activities like workshops and long-term activities like employment. Ultimately we decided that this doesn't need to be a visual differentiation as the difference will be obvious due to the date ranges. If necessary, Gemma can also add a job title before the studio posts.
+Branch: `master`  
+Dir: `_site`  
+Build command: `npx @11ty/eleventy`
 
-We potentially want to hide _Writing_ to begin with. We'll set up a few utility classes like visually hidden in order to do this.
+This tells Netlify that when some change happens on the `master` branch<sup id="ref-12"><a href="#footnote-12">12</a></sup>, it should run the build command `npx @11ty/eleventy` and deploy any files in the `/_site` directory.
 
-## Accessibility
+### Editing content
 
-It's very important to consider accessibility from the get-go. We think this should be fairly straight-forward as there will so little JavaScript. It's mainly Arena section that could be problematic, but Piper will look in to this.
+To edit content locally, open up your local site files in your preferred text editor<sup id="ref-13"><a href="#footnote-13">13</a></sup> and then fire up your local server by running `npx @11ty/eleventy --serve`.
 
-As an option, we could add a small toggle in the footer that will increase the contrast throughout the site.
+TODO Some information about where the files are stored, markdown, etc.
 
-##  Browser support
-We'll prioritise modern browsers, but it would be great if this works well on old browsers too. It's such a simple site that this shouldn't be such a big ask. It may just mean using `float` instead of `flexbox`.
+### Editing styles
 
-## Arena section
+TODO Obvi it’s mostly CSS, but will include guidance about how to tweak colours easily, in particular.
 
-The site will use Arena's API to display any channels found in a specific Closed channel belonging to Gemma (e.g. `My Website`).
+### Committing and pushing changes to the remote repository
 
-We spoke about making this more visual but adding a grid of small thumbnails. This would function to add some more visual interest to the page, and give people a better overview of the contents.
+TODO
 
-## /thinking
+### Forking this project
 
-If we go down the route of having _Thinking_ as a separate page on mobile, we'll need to work out what to do if people navigate directly there on desktop. One idea would be to simply reverse the two panels.
+TODO Want to add guidance about how someone could grab this and tweak it for themselves.
 
-## /writing
+## Footnotes
 
-The blog will be built with markdown and a static site generator.
+<ol>
 
-We discussed on whether to implement pagination or infinite scroll, but ultimately decided we were more philosophically aligned with pagination.
+  <li id="footnote-1">GitHub is just one of many remote repository hosts. GitLab and Bitbucket are two others that are commonly used with Git. All of them have pros and cons (particularly related to pricing). For the purposes of this project, GitHub is useful since it integrates pretty seamlessly with a lot of other software.&nbsp;<a href="#ref-1">⤴️</a>
 
-## Images
+  <li id="footnote-2">The command line is a way of giving commands directly to a computer’s operating system. To give commands, you use a command line interface (CLI). This is kind of the opposite of a graphical user interface (GUI) in that there aren’t any nice buttons to push or text inputs to fill out. Mac computers come with a CLI called Terminal, and newer versions of Windows have Windows Terminal. There are a bunch of other CLIs out there, search around if you’re not satisfied with your default one.&nbsp;<a href="#ref-2">⤴️</a>
 
-One big consideration is how to host images. Image files can obviously be really big, which realistically means we'd need to host them on a CDN.
+  <li id="footnote-3"><code>cd</code> stands for “change directory”. You use this command to move around your filesystem. <code>cd ..</code> navigates up a directory, <code>cd -</code> navigates to the previous directory (back), and <code>cd ~</code> navigates to your home directory. So for example to get to the Sites folder on a Mac – the default place to put this sort of thing – you would run <code>cd ~/sites</code>.&nbsp;<a href="#ref-3">⤴️</a>
 
-We also want to consider the speed of the site. Everything else is so simple and will load really fast, but images will potentially load slower in other locations or on slower connections. We also want to implement responsive image handling.
+  <li id="footnote-4">For more information about the command <code>git clone</code>, see <a href="https://help.github.com/en/articles/cloning-a-repository">GitHub’s documentation</a>. <code>personal-website</code> will be the name of the folder that the system creates to store all of the files in this repo; change it to whatever you want.&nbsp;<a href="#ref-4">⤴️</a>
 
-We discussed the approach used on [e-flux](e-flux.com), which loads a simple ASCII pattern first before loading the images. They have a separate source for this patterned background. 
+  <li id="footnote-5">You’ll notice that the <code>/.git</code> directory starts with a full stop. That means that it is hidden folder, so it won’t show up in your normal file GUI such as Mac’s Finder. Hidden files are normally important for system purposes and can be kind of “delicate”, hence the reason for hiding them from most users. If you want to see them on a Mac, open up a Finder window and type in the shortcut <code>command + shift + .</code> <a href="#ref-5">⤴️</a>
 
-Piper suggests using Arena as the CDN, creating a separate channel to collect any images to be used on the blog.
+  <li id="footnote-6"><code>npm</code> stands for Node Package Manager. It’s probably one of the most widely used platform for getting and managing dependencies. You can take a look at this site’s dependencies by looking at the <code>package.json</code> file in the root of this project. The dependencies themselves will be placed in a <code>/node_modules</code> folder. We ignore this folder using the <code>.gitignore</code> file since we don’t need to track changes in those files (that’s what <code>npm</code> is for!).&nbsp;<a href="#ref-6">⤴️</a>
 
-If we use Are.na for image hosting, we couldn’t go down the Medium route for progressive image enhancement, since they actually load two separate images. With Are.na, we’d only have a single image URL to play with and won't have access to their actual CDN.
+  <li id="footnote-7">Static site generators take a bunch of templates and content files and compile them in to a web-ready folder of HTML, CSS, JavaScript, and media files. One of the classics is Jekyll, written in Ruby and used widely on GitHub Pages. One advantage of a static site generator over a database-driven site such as WordPress is that the loading time can be a <em>lot</em> faster. There is also a lot less to manage and worry about; there’s no risk of SQL injection since there is no database, and you don’t have to consider things like keeping PHP up-to-date since you don’t need it! On the flip side, since static sites aren’t relational, they can make more dynamic queries such as search a little tougher. <a href="https://www.hawksworx.com/blog/adding-search-to-a-jamstack-site/">Still do-able though</a>! <a href="#ref-7">⤴️</a>
 
-We both agree that using Arena instead of introducing another service is the most elegant solution. We could potentially display a gradient on load, with colours picked from the image itself. The fallback/MVP option would be a gradient using the two colours of the site.
+  <li id="footnote-8">Updating Node.js and NPM can be a little fiddly. NVM (Node Version Manager) can be really useful for managing versions. <a href="https://duckduckgo.com/">Search online</a> for update tips that are specific to your operating system.&nbsp;<a href="#ref-8">⤴️</a>
 
-We discussed how to host videos, but decided that this will be implemented in the future as it's not essential. The main consideration is that embedding something from Youtube also means adding tracking to the site, which we want to avoid at all costs.
+  <li id="footnote-9">For the purposes of local development, global installation usually means it is available on your computer. This is a good thing to do for things like <code>npm</code> that you probably use often across lots of different projects. Local installation means you’re using it in the particular directory where you’ve installed it. <a href="https://nodejs.org/en/blog/npm/npm-1-0-global-vs-local-installation/">Read more</a> <a href="#ref-9">⤴️</a>
 
-## Metadata
+  <li id="footnote-10">BrowserSync is a useful tool for local development and content editing with static site generators because it live-reloads the page as you change local files.&nbsp;<a href="#ref-10">⤴️</a>
 
-We need to consider how to add credits if a post has been co-authored by someone else, or has been originally published somewhere else. This should be in the metadata and not just in the body.
+  <li id="footnote-11">FTP stands for File Transfer Protocol. There are a bunch of worthwhile FTP GUIs out there such as Transmit by Panic. If connecting to your host via FTP, make sure you are on a network that you trust and try to use SFTP if possible. It is a little frowned-upon to just replace files via FTP on-the-fly, some people refer to it as going commando. That is because it introduces a bit more possibility for user error (for example, accidentally dragging something in to the wrong folder) than using a deployment tool such as Beanstalk or DeployHQ.&nbsp;<a href="#ref-11">⤴️</a>
 
-[Jekyll](https://jekyllrb.com/docs/posts/) gives a good overview of how the markdown files can be structured, including how to add metadata, like tags.
+  <li id="footnote-12">We use branches in Git to branch out from one point in the Git history and work on that in isolation. It’s particularly useful when people collaborate on a codebase together so that they don’t step on each other’s toes too much, particularly if someone is exploring something experimental or trying to fix a bug. The <code>master</code> branch is the original branch, the trunk, the one that all other branches ultimately come from. It’s a good idea to keep the <code>master</code> branch production-ready. If the repo is hooked up to something like Netlify, then this is usually the branch that Netlify watches and deploys.&nbsp;<a href="#ref-12">⤴️</a>
 
-Tags will need to be URL-readable (lowercase and with dashes instead of spaces), as seen on [Pinboard](https://pinboard.in). Down the track, we'd like to be able to add private tags (by appending a . before the word) and to add descriptions to tags.
+  <li id="footnote-13">There are a <em>lot</em> of text editors out there that are geared towards web development. Ideally, you should get one that will have a few packages / plugins available that make your life a little easier (lots of syntax highlighters, command line tools, linters, etc.). VScode, Atom, or Sublime can be good places to start. If using VScode, you should be able to open this project from the command line by running <code>code .</code> from the root of the project.&nbsp;<a href="#ref-13">⤴️</a>
 
-## Search
-Is this necessary? Piper finds it very useful on her own site, but it could be also something to add down the line. Piper will consider this when she researches the tech stack.
+</ol>

index.html

@@ -0,0 +1 @@
+<!doctype html><html><head><title>Page title</title></head><body><p>Hi</p></body></html>