This is a simple website for publishing a CV, research and writing. It will be used for gemmacope.land.
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.
We’re using Git for version control and GitHub as a remote repository host1. Because of this, our first task is to create a local copy of the repository (repo) on your computer. Open up the command line2 and then use the command cd
3 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
4. 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
5 files that are helping us with version control.
Next, we need to install the dependencies using npm
6. One of the core dependencies for this project is Eleventy, a static site generator7. Check that you have npm
installed globally8 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 to get what you need. If your version of Node.js is too old, you’ll need to update it9. 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 ready for use. Run npm run serve
to fire up a local web server. You’ll see a bunch of output related to writing, processing, and watching files. Once the output shows the BrowserSync10 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).
To deploy the website to a more traditional web host via FTP / SFTP11, compile the website by running npm run build
. This will put all of your website files in to the output folder /_dist
.
Alternatively, hook the repo up to Netlify. Here’s a step-by-step guide. These are the settings you’d use:
Branch: master
Dir: _dist
Build command: npm run build
This tells Netlify that when some change happens on the master
branch12, it should run the build command npx @11ty/eleventy
and deploy any files in the /_dist
directory.
To edit content locally, open up your local site files in your preferred text editor13 and then fire up your local server by running npm run serve
. Watch out for compilaton errors in your Terminal window while you are editing content.
Before you edit your content, it is good practice to run git fetch
to get remote updates and git pull
if there are any updates. And of course, be sure to push your edits with git push
when you are done and ready to publish them.
The content is primarily written in Markdown, so please refer to their documentation for syntax tips. Keep an eye on your curly quotes and apostrophes. Within the Markdown files, you will find frontmatter at the top of the file delimited by ---
. This defines important structured data written in Yaml that is separate from the main page content found beneath the frontmatter. If you need to put :
or -
characters in any of your Yaml content, you should wrap it in quotations.
All of the content files can be found in /src
. As a general rule, you should feel confident editing Markdown files (files ending in .md
). You can also edit template files (.njk
), styles (.css
), JavaScript (.js
), or data (.json
), but changes to these files may require more delicate consideration.
The content that you will edit most frequently is:
/src/activity
– Used to populate the activity list on the homepage/src/pages
– Includes your main pages (Home, Thinking, etc.) as well as default pages such as Privacy/src/posts
- Used to populate the Writing feedWithin each of these directories, you may find a /_drafts
folder. Files within this folder will not be published, so you can safely keep WIP files within these folders. See the demo markdown files within these folders for examples of how to format content.
You may also find a .json
file within these folders. These data files set default values for their sibling .md
files so that these values do not need to be rewritten again and again.
TODO Obvi it’s mostly CSS, but will include guidance about how to tweak colours easily, in particular.
TODO
TODO Want to add guidance about how someone could grab this and tweak it for themselves.
cd
stands for “change directory”. You use this command to move around your filesystem. cd ..
navigates up a directory, cd -
navigates to the previous directory (back), and cd ~
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 cd ~/sites
. ⤴️
git clone
, see GitHub’s documentation. personal-website
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. ⤴️
/.git
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 command + shift + .
⤴️
npm
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 package.json
file in the root of this project. The dependencies themselves will be placed in a /node_modules
folder. We ignore this folder using the .gitignore
file since we don’t need to track changes in those files (that’s what npm
is for!). ⤴️
npm
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. Read more ⤴️
master
branch is the original branch, the trunk, the one that all other branches ultimately come from. It’s a good idea to keep the master
branch production-ready. If the repo is hooked up to something like Netlify, then this is usually the branch that Netlify watches and deploys. ⤴️
code .
from the root of the project. Atom’s equivalent command is `atom .`. ⤴️