Hugo

Three questions on Academic-Kickstart files: shell files, editing practices, parent directories

I recently forked/cloned the Academic-Kickstart for the Academic theme and had 3 sets of questions:

What to do with Shell files in the root directory?

The root Kickstart directory has two files update_academic.sh and view.sh. What is the purpose of these files? Is there a reason to keep them in my own website directory and/or push them to Github given I’m deploying and building via Netflify?

Best-practice to edit root directory or example website in theme subdirectory?

In the root directory, there is essentially an entire website containing a config.toml file, public subdirectory, etc. If one then goes into the /themes subdirectory, there is the theme structure and an example website. When building our own website using the Kickstart directory, is it recommended to (a) edit the files in the root Kickstart directory, (b) edit the example site found in /themes/academic/examplesite/? My inclination is build my site by editing the root Kickstart directory, but perhaps I’m missing something because it seems odd edit this directory given it will ultimately mean the files I’m pushing to my Github repo for Netlify will contain an example website within /themes. Simply delete the example site? What else should be deleted?

Building a site where /layout and /theme are parent directories of the /content and /config directories?

If one goes from the root directory to themes/academic, there are many additional files presumably defining the theme and an example website at themes/academic/examplesite/. However, the examplesite subdirectory only has /config, /content, and /static directories. I am confused how these files can be used to generate a site: wouldn’t we need to add a /public directory and a \layouts directory to themes/academic/examplesite/ to build a website that uses the Academic theme? More generally, shouldn’t our /config and /content subdirectories be in the root directory and the theme files should be in a child of the root?

I don’t use Academic, but I know a lot of this is explained at https://sourcethemes.com/academic/docs/customization/.

If you ever want to know what a shell script (a file ending in .sh), just open it in a text editor! Most documented scripts will at least give you an indication of it’s purpose, and hopefully contact info for the person that made it. :slight_smile:

1 Like

The documentation explains how to edit the docs to create your own site and I’ve now created and deployed several sites with this theme, but it’s completely silent on each of these (doesn’t even mention the existence of .sh files!) and the specifics of the Kickstart files (versus working with the Demo). For (1) and (2), I find it annoying to have lots of random files cluttering up my sites and for (3) I don’t understand how this could possibly work.

From https://gohugo.io/contribute/themes/#adding-a-theme-to-the-list

The folder name here— exampleSite —is important, as this folder will be picked up and used by the script that generates the Hugo Theme Site. It mirrors the root directory of a Hugo website and allows you to add custom content, assets, and a config file with preset values.

It’s for the theme showcase, you aren’t expected to build a site with it; though many exampleSite directories may have additional configuration details about copying it to where it needs to be.

My prior answer spoke to this.

I think you’ll have more traction asking the theme creators. Well, for (1) ( What to do with Shell files in the root directory?), that’s their thing, so ask them why they do that and if you can change it.

For number (2) ( Best-practice to edit root directory or example website in theme subdirectory?), the link I shared spoke directly to that question.

To override a template in the theme, you simply copy the file you are interested in from themes/academic/ and paste it in your site folder using a similar path. To understand how this works, you should familiarize yourself with template lookup.

So, I guess I didn’t speak to:

I don’t know. You’re using git. Delete them, build the site, does something bad happen? If so, rollback.