HO HO HO, and Welcome.

This is your brand-new, never-seen-before site. It might be a bit intimidating to operate (I will admit that some sleighs have more of a learning curve than others) so here’s a quick instruction manual on the basics. If you have more in-depth questions or need to re-configure things, I recommend calling tech support where one of our elves (Lev, but in a funny hat and having inhaled some helium) can help you out. Alternatively, if you have time and feel like messing around and figuring it out yourself, go for it. It’s pretty hard to permanently break this thing.


OK So What Is This?

This is a website built with Hugo, which is a static site builder. What that means on a technical level isn’t super important – what matters is that you write pages for it in Markdown files, and then Hugo compiles everything into a fully formatted website. This particular Hugo site is built with a theme called PaperMod, which also isn’t really going to matter to you but is worth documenting here anyway.


How Do I Edit It?

I’d reccomend using Atom! Atom is an open source text editor which is amazing in all kinds of ways but the important thing here is that it can open a project folder and highlight Markdown syntax. Installing it is pretty easy – just go to www.atom.io (or click the highlighted word “Atom” from the start of this paragraph), click the big yellow Download button, and then open it when it downloads and follow the installation instructions. If you get confused, ask the Tech Support Elf (who is probably sitting next to you currently and has maybe already installed this on your computer).

Also, note for that Elf, please click here to make sure you installed everything right.


Markdown, You Say?

Yes! Markdown! Markdown is a type of file where you can write in text with formatting, but the file still stays pretty legible. My favorite part about it is that it’s not proprietary to any particular program, and can always be opened as a plain text file if all else fails. Anyway, here’s a screenshot of what this page looks like as I’m typing right now. A good cheat sheet for writing in Markdown can be found here. That will probably cover about 90% of anything you will want to do on here, but if you need more information that same website (markdownguide.org) has very thorough documentation.

In this file you can see that I’m marking headers with “##” (indicating Header 2) and links are formatted with brackets around the word that will be displayed and the link in parenthesis following that. So a link to the blimp.levlevlevlev.com site might look like this [blimp.levlevlevlev.com](https://blimp.levlevlevlev.com)" (although if you’re looking at the .md file for this page you’ll notice that I’ve had to use some fancy backslashes to disable that link from being displayed the way it would be normally for demonstration purposes).


Quick Reference of Useful Syntax

(most of which can also be found on the cheat sheet):

Formatting Syntax to Write It
Header 1 # text
Header 2 ## text
Header 3 ### text
Bold **text**
Italics *text*
Block Quote > text
Bulleted List - text
Numbered List 1. text
Link [text](link url)
Line Break {{< br >}}
Horizontal Divider ---
Image ![optional alt text](image-path.png)

Note that the {{< break >}} is a function that I have coded into this website and isn’t applicable to all Markdown formatting (although many other editors have their own syntaxes to write a line break.)

Also this is what a blockquote looks like (I usually use them as comments) and the above part was in bold and italics which can be written like this: ***text*** and looks fun I think. 1

I’m going to cut it off there, because I don’t want the table to get too long. If you ever want to jump back to that in the future, you can save links with headers by mousing over them and clicking on the “#” that pops up on the right side.

One other note that is important for when you’re writing website files is that most of the time you’re going to be using local filepaths rather than absolute URLs. Does that sound complicated? It isn’t really, but it can take a bit to get used to. But to understand it properly, I need a new section, so check out Site Organization & Structure. Before we get there, though, I want to go over a few other basics.



Basic Operation


How to Make a New Page

In all honesty, I have no idea how you’re planning to use this website. Maybe it won’t work for what you want at all. But here’s the easiest way to make new pages.

  1. Open Terminal
  2. Type one of the commands I’ve given you along with what you want the file path to be (with no spaces!) For example: addR newResearchFile (here, “newResearchFile” would be the filepath assigned to that file).
  3. The page will automatically open in Atom, where it will have been placed in the correct folder and have the format template waiting for you.
  4. Write your content, and then save it at the end like you would in any other application.

How to See Your Site Locally

Your site is hosted on the internet at www.tully.page, but if you want to see what it’s going to look like before uploading it or are editing it on a plane and American Airlines is denying you WiFi but you desperately need to find that thing you wrote last week, you can type callTully in Terminal and the site will load in Chrome on a localhost:1313 page. Once you’re done, you can close that window like any other tab, but the server will still be running. To stop it, go back to that Terminal window and press CTRL + C to stop the server.


How to Upload Your Site to the Internet

The real way to do this is to navigate to your Tully folder in Terminal and typing hugo && firebase deploy, but doing that requires that you know some basic commands in terminal and also can be annoying if you do it often, so I made a shortcut for you that works from anywhere. Here’s how it works:

  1. Open Terminal
  2. Type uploadTully and press enter. You should see some stuff happen in that window which will end with the text:
✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/tully-blimp/overview
Hosting URL: https://tully-blimp.web.app

If you now go to www.tully.page, you should see your updated site (or sometimes you have to wait a bit for the changes to populate, but eventually it will be there)!



More Advanced Stuff


General Organization & Structure

This is maybe the most technical section, but I’m going to try to explain it as simply as I can. Hugo stores the site in a bunch of nested folders. The outer one for this site is simply called “Tully” and within it are some of others. You can see all of this in Finder, but I like to work on the site in Atom (which hopefully you installed back in How Do I Edit It?). This is what my window of Atom looks like when I open the Tully folder: You can see that within the Tully folder are a bunch of other folders (.firebase, archetypes, etc.). The primary one that you will use in the day-to-day operation of the website is content. I’m sure that the Tech Support Elf is happy to explain what the other ones do in detail, but this page is only going to really explain the content folder. Within the content folder are other folders for sections of the website (fromLev, instructions, etc.).

Note that just adding a new folder does not automatically add it to the menu bar up top. If you want to change the menu bar I’d recommend calling the Tech Support Elf because you have to edit the config.yml file.

When you add a new file using the method described in the How to Make a New Page section above, it goes into one of these folders. 2 Because this folder structure is how Hugo compiles the site, making sure that files are in the right folder is how you make sure they’re in the right place on your website.

The only other folder you might end up dealing with on a regular basis is the static folder. This folder contains things that don’t get modified by Hugo when it’s compiling the site. This could things like include images, videos, and HTML pages. While you can store images and other things within page bundles (see the Index Files section for more information on those), anything stored in the static folder is really easy to reference from anywhere on the site, so it’s a good place to keep any resources you think you might need frequently. For a more technical explanation, see here.


Local References

Most of the time that you want to link to something somewhere else on this website, you’re going to want to do so without just putting the full URL in. Here’s how you do that.

For a Folder:
Set up a link like you normally would [Display Text](www.link.domain) and then change the part in parenthesis to match the file path of the thing you’re trying to link to. For example, the link from here to the fromLev folder would look like this: [Display Text](/fromlev/).

For a Specific Page:
If I wanted to link to a specific file in that folder (and not just the index page), I would write something like [Watch This](/fromlev/benfolds-muppettheme/). Note that although this is a .md file, I’m not putting that in the link.

For an Image:
Linking to an image, as mentioned in the Quick Reference of Useful Syntax is like a normal link but with an exclamation point in front of it ![alt text](image-path.png). However, for images the file path needs to include the ending (e.g. .png, .jpg) for the link to work. Here’s what the link for the screenshot of my Atom window looked like: ![](atom-interface.png). Note that because we’re already in the same folder as the image, it doesn’t need any path information other than the file name to find it. If you want to add Title Text to an image (the way XKCD does with the floating note), you could write ![](/ciceroPosing.jpeg "he seems cool"). Importantly, unlike folders and files which want the path to be all lowercase, images NEED the file name to have the correct capitalization. Also worth noting is that example is a link to an image in the static folder, so it can be referred to simply with a forwardslash and then the file name.

I know that was a lot. Sorry. I hope it’s helpful though. Anyway, here’s a fun and easy section to make up for it.


Embedding YouTube Videos

To embed a YouTube video (as seen on this page) type this into your Markdown document: {{< youtube bunchofletters >}}. That “bunchofletters” is the video ID, and can be found by stealing the end of the Share link. So if you have a link like https://youtu.be/WovVQ7V7pHQ your video ID will be WovVQ7V7pHQ. If you then substitute that into the {{< youtube >}} thing so you have {{< youtube WovVQ7V7pHQ >}} it will embed the video!

I can’t put it into my normal code snippet formatting because it will just show you the video, but I promise it works.

Also, tweets can be embedded similarly with syntax like {{< tweet user=“JudeAtwood” id=“1468030063819964424” >}}, the information for which can be found by clicking the embed button in Twitter. I know you don’t really use Twitter, but I figured it was worth including here.



Index Files

Index files are special. You’ll notice that each folder in the content section has one, and that it’s the file that gets opened when your URL is displaying the folder path (e.g. www.tully.page/instructions/). In Hugo there are two types of index files:
_index These files (the ones with underscores at the beginning) act as directories for the folders they’re in, and are great for making a landing page displaying a bunch of articles or posts or whatever. In technical terms, this is the index page for a leaf bundle. The page you see when you go to www.tully.page/fromLev/ is an _index file.
index Index files with no underscores look like normal pages, but are similarly the opening page for a folder. In technical terms, this is the index page for a branch bundle. This page (www.tully.page/instructions/) is an index file.

If you want the real documentation on it, click here for the Hugo “Page Bundles” explanation, which delves more into the idea of leaf bundles and branch bundles.



Conclusion

I think that’s most of the main things you need to know? There’s a lot more under-the-hood stuff that I’ve skipped to try to keep this to a manageable length, but I’m sure I’ve missed some really basic, essential thing. When you inevitably run into that, just yell and I’ll probably hear you. Unless I’m back at college, in which case I definitely won’t. Anyway, I hope this site works well for you. If not, then at least I had fun making it.

- Lev, December 2021











  1. Also, one more bonus piece of formatting: this is a footnote! I notoriously love footnotes, and if you want to use them it’s as easy as writing [^1] wherever you want to put in the footnote, and then going down to the bottom of your Markdown file and writing [^1]: footnote text there. It will automatically format all of your footnotes when the page renders, even adding in these nice little arrows you can click to return to where you were on the page when you clicked on the footnote. ↩︎

  2. As a note, it formats it based on files in the archetypes folder, but we’re not going to go over how to edit those archetypes here, just because this is already a long page. ↩︎