Run locally to see how your website looks

On RStudio, your site can be built locally so that any changes you make can take effect in real time. This was super helpful. I found that running blogdown:::serve_site() and viewing my site in the “Viewer” pane on RStudio was slightly laggy, so I opened the local URL (http://127.0.0.1:4321/) on my browser, and the site still reloaded every time I ran blogdown:::serve_site(). However, sometimes it opened up a new page; I didn’t realize this at first, until I saw that many previous iterations of my homepage were taking up all my tab space. I ctrl + w’d for days.

Making new separate widget pages

This was by far the most important thing to me, but also the most challenging to implement. A lot of other static sites only had two pages: one page with all of the info placed inside “widgets”, and another page for just blog posts. Widgets are basically sections on your page, and there are a lot of widgets that are very nice to look at and can really spruce up your site. This one-page format works well for some people, but I knew I wanted separated pages with only a couple widgets instead of one page with a lot of widgets. There are two reasons for this: I dislike scrolling up and down on a seemingly endless page (because I am easily distracted), and I wanted to categorize all the facets of my life into separate pages (because I am notoriously organized to a fault).

There really wasn’t a lot of documentation on how to do this, apart from a short section in the Academic documents on how to create a new widget page. It honestly was easier said than done, because the way the folders in your repo have to be organized and named is important. So, here goes.

In your root/ folder, navigate to the folder titled content/. These subfolders inside are the bones of your site. The contents that go into the widgets are all organized as subfolders within the content/ folder. This needs to be shouted from the rooftops for how much trouble it caused me, so let me reiterate: the subfolders in the content/ folder do not correlate specifically with different pages. Instead, subfolders, like project/, publication/, and post/, are referenced by different widgets which may be on different pages on your site, but all of these subfolders have to be in the top level in your content/ folder.

To make new pages, make new folders! Do not change any of the other folders (or do, if you know what you’re doing. I’m not your keeper. Just saying, I wish someone told me not to change the other folders).

For example, here is how I made new page for “Research”:

1. In the content/ folder, make a new folder called research/
2. Move the markdown file called _index from content/project/to content/research/ folder and rename it to index
   • don’t ask me why because I don’t know why; it works for Allison Hill and it works for me
   • in index, add YAML front matter as documented here
3. Add widgets into the research/ folder
   • more on widgets below!
4. To link these new widget pages to your menu bar, navigate to the config/_default/ folder and open the menus TOML file.
   • see how the url for all the pages start with a hash #? That means that it is looking in your homepage folder content/home/
   • in order to link to another page, delete the # and add a / at the end, e.g., url = research/
5. Repeat for other pages. Make sure new folders that are created have an index file, populate the folder with all the widgets you want on the page, and edit the menus file

Great! Cool! New pages!!

Okay. Now, adding widgets to your new page. This part stumped me for the better part of an afternoon.

Using the “Research” page as an example again, let’s say that you want to have a “Portfolio” widget that showcases your projects. For each individual project:

1. Inside the now-empty project/ folder, create a further newproject/ subfolder that reference a project
2. Within this newproject/ subfolder, create another index file.
3. Add some YAML front matter (title, summary, tags)
   • of importance is the tags front matter: use informative tags and remember what they are!
4. Write about your project!
   • you can also add a featured JPG or PNG
5. Then, create a “Portfolio” widget within the content/research/ folder
   • the easiest way to do this is by copying the projects markdown file from the content/home/ folder
   • make sure that your pages are rearranged in the order you want using weight
   • the projects file can be renamed to anything
6. In the projects file, under [[content.filter_button]], rename the tags, and change the tag = to refer to the tags you used earlier
7. Edit your widget to your heart’s desire!

One page down, one more to go! I basically repeated this process to create my “Outreach” page, except using other widgets that I wanted. Learning to create a separate page was definitely an uphill battle, but after figuring that out (and become familiar with blogdown and my repo), it was smoother sailing to create more pages. I say “smoother” because the next challenge was creating a “Posts” page. More on that below.

Filtering posts by tags/categories

I was able to make my research projects filterable by tags and my publications filterable by publication type in a drop-down menu. I still cannot figure out how to achieve the same thing with posts; I’m envisioning a drop-down menu where I can select “Month/Year” or “Category” and then only posts that match the date or category will pop up. Perhaps the “Posts” page for blog posts is inherently different than “Projects”, but also this makes no sense because static pages are static pages are static pages, right? Please contact me if you have any insights.

In any case, I created a “Journal” page where I have all of my posts. In this page, I linked all the tags and categories by referencing to the tags and categories path. To keep track of the dates which I published posts, I assigned each month to another tag. For example, I added “2020-May” as a tag to denote posts published during the month of May in 2020. Then, I linked a reference to tags and categories.

The Markdown code to reference something (e.g., blog post) within your site is {{< ref "/post/blog-post" >}}. The part in quotes is the permalink, or slug, to your blog post. As long as one of your blogs has that URL, then you are able to reference it anywhere in your site. You can link this by using the syntax [linked text](link). However (and this part is annoying): this doesn’t work for R Markdown. For blog posts, which are written in R Markdown, I just link the URL of whatever I want to reference.

So, putting it all together, I reference blog categories and tags in 2 ways:

• [category]({{< ref "/categories" >}}) and [tags]({{< ref "/tags" >}}).
• [category](vickimzhang.rbind.io/categories}) and [tags](vickimzhang.rbind.io/tags).

This isn’t the most optimal solution yet for me, since I think filtering using a drop-down menu would be much more elegant and intuitive. However, it works.

Set Up

You only need to do this once!! (You need the git command line downloaded.)

1. Open git bash

2. cd Documents/vmzhang-academic

   Change your working directory to the root/ folder.

3. git init

   Initialize that folder (basically making that the local folder that is linked to your GitHub repo).

4. git add .

   Add all the files in the local folder (telling git which files you want to add; by default, it adds all of them).

5. git commit -m "initial commit"

   Commit the files that you just added (confirming the files you just added and prepping them to be pushed).

6. git remote add origin https://github.com/vmzhang/vmzhang-academic.git

   git remote -v

   Set and verify your remote (replace the URL with the URL of your GitHub repo - this links your local folder to your remote GitHub repo).

7. git push origin master

   Push upstream from origin to master (aka push all the files that you just added and confirmed from your computer to GitHub).

Subsequent changes

Only 3 lines of code!!!

1. cd Documents/vmzhang-academic

   Locate your local folder directory.

2. git commit -a -m "new additions/changes"

   Here, you are combining a bunch of steps together in one line of code: -a means that you are adding all the file changes that were made, the code after -m is a message stating what was changed, and you are committing everything.

3. git push origin master

   Push all committed changes.

For every change and every new blog post, I just open git bash and run those three lines. More git commands can be found here, but I probably won’t need them within my workflow. Git and GitHub are important, crucial, useful, etc., but it doesn’t mean that I am good at using git command line (yet!).

Speaking of GitHub, here’s another tip that really helped me: I found static sites using Hugo Academic that I liked, then tried to find that person’s GitHub and subsequently tried to find their website repo. Just clicking through their repo files really helped me organize my folders locally. Just Google the name of the person’s website plus “GitHub”. Not going to lie, I was lurking on so many people’s GitHub accounts.