menu

Academic

Chat about Source Themes Academic, the page builder for Hugo 👩‍💻📝🚀

Channels
Team

The deadly rabbit hole of the Academic theme

May 13, 2020 at 2:16am

The deadly rabbit hole of the Academic theme

May 13, 2020 at 2:16am
The academic theme has been extremely useful to many, many people, including me, and I and others are grateful for its creation and free distribution. However, my own experience as well as the questions asked here make it clear that the documentation is great for initial set-up but only documents a small fraction of the types of customization that users need. Things that are common needs and should be extremely easy, such as putting one word in a title in italics, are so complex that no one here can explain how to do it.
Academic actually sets up a deadly rabbit hole because:
  1. The theme looks good and advertises itself as being easy to use and easy to customize.
  2. The documentation is very good on how to set up the theme, perform some basic content editing, and make limited global built-in customizations (such as changing all font sizes globally)
  3. The documentation on how to do any other customization is wholly inadequate for anyone who is not a Hugo expert.
  4. The theme is so unbelievably complicated in the level of nesting for templates that only a Hugo expert can follow the transclusion, variables, and other nonobvious elements of the site build in a way that they can actually make these changes.
- this is not a criticism of you or your great work on Academic, but I think it's important to understand what non-experts are facing and to change the Academic page description.
I'm not saying that the theme documentation must cover extremely strange and unique customizations. I'm saying that the site architecture is such that even making what would seem to be a straightforward change like italicizing an individual word cannot be done with basic knowledge of markdown or CSS, but requires expert Hugo knowledge. Another example is trying to have the 'Presentations' section list the conference associated with a talk. That doesn't seem like it should be massively difficult, but it requires defining a new variable and writing Hugo code to check the variable and alter the template. This is not something that anyone who is not very well-versed in Hugo could do.
Every day people post questions about making basic, straightforward customizations and many of them go unanswered. Is anyone collecting this long list of questions to improve the documentation? I am not saying that the person or team that created Academic is responsible or owes anyone anything, but I'm guessing that many people abandon an otherwise useful project due to these difficulties. The only reason I didn't is that after investing many hours making a site and getting stuck, I literally hired a web developer to help me make some of these basic customizations.
My recommendations are:
  1. Set up some method to capture questions posted here and any posted answers, and link it to the online documentation.
  2. Change the upfront description of the Academic theme to make it clear that, although some very limited number of customizations are extremely easy, the overall site structure is extremely complicated and difficult to learn. It is only moderately difficult for a non-expert to figure out how to exclude existing sections or change a predefined list format to a card format. But it is very hard to figure out how to change aspects of the site that are more "fundamental" (i.e. the list format style itself).
  3. If you want people to be able to actually customize the theme, post a human-readable description of the strategy of how the templates relate to each other and what templates draw on which others so people have a chance of learning how the theme works.

May 13, 2020 at 2:22am
I agree. I managed to make my website and I think it looks great but there are so many simple-sounding things I'd like to modify and can't. Getting something working took many hours, and I can't afford to take all that time again any time soon, nor do I have the time to learn Hugo for real, or funds to pay someone to do it for me.
  • reply
  • like
I both agree and disagree. I agree that if you want to go outside the theme and start to customise more than documented, it can get hard very quickly. However this is also the case with pretty much every other Hugo theme. I think you have to consider the target audience for the Academic theme. It is designed for a specific user in mind, the academic who wishes to publish posts, publications, projects and documentation about their academic studies and life. This is where Academic shines. It includes pre-build templates and widgets to allow you to quickly build a site with little or no development skills being required. However, this is the reason that most Academic sites look largely the same.
I think if you are looking to create a site that is highly customised with Hugo, you will need to understand Go, CSS and Hugo templating, irrespective of the theme you have chosen. This is similar with other frameworks like Jekyll or GatsbyJS. I do think static site generators like Hugo lack a competent CMS. I have previously used themes/frameworks like Elementor on WordPress, and you basically drag and drop the site like you are creating a Word document. Whilst there are solutions like Forestry or NetlifyCMS, you still need an understanding of the underlying theme structure to be proficient, and they are pretty basic.
I do agree that the documentation could be enhanced to include more advanced customisations and changes.
Edited
  • reply
  • like
I agree that if you want to go outside the theme and start to customise more than documented, it can get hard very quickly. However this is also the case with pretty much every other Hugo theme.
The problem is that Academic makes it very hard to see up front what very limited customizations are easily available, and it explicitly advertises itself is easy to customize, but that is true only for experts.
It is designed for a specific user in mind, the academic who wishes to publish posts, publications, projects and documentation about their academic studies and life. This is where Academic shines.
The theme does not even allow users to put a word in an article title in italics. This is a very basic and extremely common aspect of academic formatting (in both humanities and sciences). So for me it shines in some places but falls badly short in others. Again, this is not a problem if the website advertised it as such, but it doesn't.
I think if you are looking to create a site that is highly customised with Hugo, you will need to understand Go, CSS and Hugo templating, irrespective of the theme you have chosen.
I am not looking to create a highly customised site. I want a simple site where I can enter my article titles and have them correctly formatted.
Have you actually compared Academic with other Hugo themes? Have you looked under the hood? The web developer I hired said he had never seen such a complicated theme. I can't comment on Jekyll or Gatsby, but the theme is sold as perfect for academics with a bit of computer knowledge, not as perfect for academics who are Hugo experts.
As I said, if there was a descriptive document explaining how the templates and the MANY partial templates interact, and how the site is designed in terms of overall structure, I would feel differently.
Edited
  • reply
  • like

May 13, 2020 at 12:35pm
As much as I love this theme, I couldn't agree more with the documentation not being beginner friendly to manage it. For example, I had to search this forum on how to use the page layouts (such as courses). My word for it maybe wrong but it is using the existing template/layout for courses. There is discussion of the layout (https://sourcethemes.com/academic/docs/get-started/#choose-the-right-layout-for-you) but how do we get started is missing.
  • reply
  • like
How did you get an academic publication? Did you research something? became an expert on one small problem in a large broad field? The same thing goes with Academic.
I'm no Code wrangler. I use Academic Straight from github. I don't use R. I compile my site on my machine and then push the compiled HTML code to github pages. I had to have tutorials for every step of the way, and then sometimes someone to help me. There is a learning curve with Golang, with Hugo, and with Academic. The first time I used Academic I didn't know to make my own layouts folder with my changes, so I changed the default theme files. That was back before version 4.4 and that version is still what I use for my personal site, though I have since deployed two other academic sites with newer versions.
Academic is a great resource/tool for those academics who are part of a lap that is creating their own website, or a who are creating their own website for hosting on their institutional web server. Many times those webservers do not allow server side scripts. Then early career academics often switch employers so they end up needing to create new online profiles. Academic Travels with you... it is really good at what it does. does take comments and considerations into his work. But, as far as I can tell, this is not his full time job. If, in your study of Academic you learn something about how something works. Write it up in a blog post for your new site. Then go fork the documentation repo on github and add the content to your copy and send a PR request for including it in the documentation.
Also be aware that many of the issues and challenges faced by people here are because they don't have an easy time with Hugo. When you are just starting out it can be hard to tell where a particular challenge is coming from in the tech stack. Hugo and Academic both have their evolution cycles. If this is something that you don't really want to deal with, then you can fork both and let them be stable in your github account, or you can go pay for a squarespace or wix site. There is no shame in paying for web services.
I have downloaded and played around with about 12-15 different hugo themes. Academic is by far cleanest straight forward approach to content management. I think it is a bit of a sham that Academia https://themes.gohugo.io/academia-hugo/ forked the theme. Of the 1500 or so people on github that have forked the theme and modified it in some way, it would be great if some of them would feed back PRs and think more abstractly about how they create solutions the challenges they encounter. A few people do contribute. And then comes the hard task of asking: is this feature widely needed? is this feature widely
There is room for improvement in the theme. Granted. But great opensource does not happen without great community. Many/most in this forum are not representative users of academic. By the numbers most users don't come to this community. It may be because they don't need it. Success is often silent. Academic has one of the best documentation sites of all the hugo themes. And yes there are things that I can't find — especially when transitioning between versions (as in what was the documentation at a particular point in the software). Something akin to how bootstrap manages its documentation per version might be helpful. But Keep in mind the theme for Acamdic's documentation is itself an instance of Academic!
BTW: Zotero the ever popular citation manager doesn't even support your italicized word in title requirement. — I know I have ran into this issue myself in my bibliographies, a long with Farsi, emojis, Japanese, and Chinese scripts in the citations.
But changing the line where the title parameter is called to include the markdownify filter, as is done with subtitles: https://github.com/gcushen/hugo-academic/blob/ebfb1d9fff5bd573bac93df9d6a7b31ddb634746/layouts/partials/pageheader.html#L59 You should be able to _titalic part of a title.
Edited
  • reply
  • like

May 14, 2020 at 8:34am
How did you get an academic publication? Did you research something? became an expert on one small problem in a large broad field? The same thing goes with Academic.
The problem is that Academic's "Getting Started" section doesn't begin with "This is a great theme to learn Hugo on and it can be customized once you learn Hugo to an advanced level." The first sentence of the documentation is "The Academic framework enables you to easily create a beautifully simple website using the Hugo static site generator in under 10 minutes." While this is possible literally true, the entire tone of the documentation suggests that the theme is easily customizable, when it is not.
I did not expect this theme to work out of the box with no effort. I spent about 3 hours installing software and setting up my initial site, which was about what I expected, despite the 10-minute claim. That's totally fine with me. But then, when trying to figure out how to italicize a word in the title, I spent over 8 hours watching Hugo tutorials, reading documentation, asking on this Spectrum site, and combing through the theme templates before giving up. That's not ok. If you are making a theme for academic use, being able to properly format an article title "Mating Habits of the Canis Lupus" is pretty important.
I'm no Code wrangler. I use Academic Straight from github. I don't use R. I compile my site on my machine and then push the compiled HTML code to github pages. I had to have tutorials for every step of the way, and then sometimes someone to help me.
Based on your description, you are not the sort of person who would be mislead by the tone of the Academic website and documentation. You are more computer literate than 95% of working academics outside of engineering and computer science, who are using MacOS and Windows and Microsoft Office or equivalent software.
Academic is a great resource/tool for those academics who are part of a lap that is creating their own website, or a who are creating their own website for hosting on their institutional web server.
I agree that Academic is a great resource, and I say so in my post.
does take comments and considerations into his work. But, as far as I can tell, this is not his full time job.
As I said, was great in creating and distributing this tool, and I explicitly said that he owes the community nothing. My main request is that he change the description of the Academic theme so it is not so misleading. I suspect that I am only one of many people that tried to set up a site and only after many hours of frustration realized that the promised customization was beyond my capabilities. That's fine, but please say so up front. If it were clear that I could set up the site but would not be able to tweak it and make small changes with a reasonable knowledge of basic HTML and CSS, I wouldn't have started down that path. I don't want to have to be a Hugo expert to tweak my website.
If, in your study of Academic you learn something about how something works. Write it up in a blog post for your new site. Then go fork the documentation repo on github and add the content to your copy and send a PR request for including it in the documentation.
I don't have a GitHub repo and have no idea how to fork things or make PR requests. If there were a wiki for Academic, I would absolutely contribute. If there were someone collecting lists of questions that could easily be browsed, I would be there helping others. But the Spectrum chat channel is not a good outlet for creating documentation and I don't see where people are supposed to do it. If you are asking people to help document a tool that advertises itself as letting you set up a website "in under 10 minutes" then there should be some way for the community to accumulate knowledge and help with documentation that doesn't require them to learn github and PR requests - a whole new tool for most of them and a workflow that was designed for software development rather than knowledge accumulation. I can't understand why there is no wiki for Academic.
Also be aware that many of the issues and challenges faced by people here are because they don't have an easy time with Hugo. When you are just starting out it can be hard to tell where a particular challenge is coming from in the tech stack. Hugo and Academic both have their evolution cycles. If this is something that you don't really want to deal with, then you can fork both and let them be stable in your github account, or you can go pay for a squarespace or wix site. There is no shame in paying for web services.
Again, I'm not complaining that Academic is inadequate or badly done. I'm unhappy that its wonderful capabilities and complex limitations are not being straightforwardly communicated. Why promote this tool as easy to customize when it is not, aside for a very limited number of things? Why not have a line early in the documentation that says, "The Academic theme is very complex structurally. While there are many options to choose from, it is not easy to change what information is displayed or how it is displayed aside from the existing options. Do not expect to be able to tweak the website elements without some advanced knowledge of Hugo."
There is room for improvement in the theme. Granted. But great opensource does not happen without great community.
I agree. I was shocked to see how this community is operating. Questions every day, no wiki, no active FAQ, no group maintaining and updating documentation regularly in response to questions. It seems to me that made a great, complex tool, wrote great documentation for 15% of its capabilities, and understandably doesn't have the time to support it in the way it needs. So he/someone should 1) create a channel where the people who are likely to use this theme - people who want professional-looking websites in "under 10 minutes" - can easily search for and document their knowledge, and 2) stop advertising this theme as an easy theme to customize with basic familiarity with command-line installation and ability to read Markdown.
BTW: Zotero the ever popular citation manager doesn't even support your italicized word in title requirement. — I know I have ran into this issue myself in my bibliographies, a long with Farsi, emojis, Japanese, and Chinese scripts in the citations.
Zotero does properly format italics in titles with use of the HTML tag <i></i>. But Academic doesn't - for me at least.
But changing the line where the title parameter is called to include the markdownify filter, as is done with subtitles: https://github.com/gcushen/hugo-academic/blob/ebfb1d9fff5bd573bac93df9d6a7b31ddb634746/layouts/partials/pageheader.html#L59 You should be able to _titalic part of a title.
Unfortunately, the link did not work for me. It would be great if this were fixed in the theme and if it was documented on the Academic site how to italicize title words.
  • reply
  • like