Visual vs front-matter editing

Hello,

I’ve just started creating a personal website, using Academic and GitHub hosting. While editing the contents of the site, I came across the following problem.

Why is the About/Bio section of my website editable graphically from the netlify.app interface (under Authors), whereas other sections (that appear right underneath in the Academic default template), such as Experience, can only be edited by editing the front matter of the relevant .md file?

Thanks!

Hi, and welcome to the HUGO Community forum.

Could you please describe your setup?.

I’m understanding from your question that you’re using Hugo with the theme Academic, deploying from GitHub to Netlify. And you’re able to edit the Bio section from some Netlify.app interface (don’t know if it’s NetlifyCMS or some other app) under the Authors section (I can’t find that section in Netlify web site).

Please add some screenshots if it’s possible or necessary.

1 Like

Hi Odair, thanks for replying, and sorry for the missing info. I am indeed using Hugo with the theme Academic, deploying from GitHub to Netlify. The Bio section is editable from siteName.netlify.app, in an interface like this & this, after choosing the Author in the right hand side.

On the other hand, content of default sections such as Experience is meant to be edited by directly editing the frontmatter of the corresponding .md file, which is done not in the Netlify interface, but through GitHub. I will post a link to the Academic doocumentation in the next post, as I am not allowed more than 2 links per post.

This is a bit more cumbersome but it’s ok - I just want to understand why not all the content in the Academic template is editable from the same place. Also, once I edit /content/home/experience.md (directly from github) and commit that edit, the change is not visible on the website, whereas edits made through Netlify are.

I’m very new to this all, hence the confusion & silly questions! Thanks again for your help :slight_smile:

Ok, take a deep breath and full yourself with patience.

I have not experience with Academic theme and I see it a little bit complex for a beginner, but I hope that this does not discouraged you to put your site online.

First at all, the interface that you mentioned is named NetlifyCMS, this is a React.js application that allows you to edit your .md files, according to the configuration that you provided in the admin folder of your project.

It is important to understand that you’re working with a site under the JAMStack way of develop, for that reason, the site will live in a CDN provided in this case by Netlify that also provides the tools for compiling your site, in this case Hugo among others. But the source code as you know is hosted in GitHub, and then, every change that you do in your code via direct edition or via git commit, will trigger a build instance inside the Netlify platform.

NetlifyCMS have to be configured to edit your site code hosted in GitHub via an authentication layer provided by Netlify itself (don’t confuse Netlify with NetlifyCMS), in this way, NetlifyCMS is able to write direct to your GitHub repository. But this is not the only way that you have to edit posts, just is a more human way to do that.

For simplicity let me explain you something:

  1. In the JAMStack model, the source code of your site is hosted in a source code repository like GitHub, GitBucket and GitLab. You can edit your code mostly locally, commit the changes and push those changes via git commands.
  2. When your repository is updated with the push command, it will trigger a build instance inside Netlify cloud that will clone your repository. Then, some virtual machine is borrowed to you for a very short period of time and a build script is launched. This script will read the netlify.conf file (that was cloned from your repository along with the rest of the source code) to load the build commands. In some simple cases a netlify.conf file it is not necessary, but it is a good practice to have one.
  3. That virtual machine will compile the source code and if the build step is successfully, Netlify will deploy the entire site to its CDN (Content Delivery Network), and you will be able to browse your site at the URL that you have configured inside your Netlify site config.

As you can see, NetlifyCMS is not necessary to have a complex website deployed in a CDN. Usually one include it when is delivering some web solution to a customer that does not have the skills to edit text files and commit the changes to a git repository.

Finally, I recommend you to start with a more simple site, without CMS, using git as I explained. This guide of the Hugo docs will be useful (Don’t jump the QuickStart guide). Learn how to build a hugo web site locally with Ananki theme, then try with more complete themes. When you feel comfortable with hugo locally, jump to Netlify, and when you have the necessary understanding of how static web sites come to life in a CDN, try to include the NetlifyCMS, or maybe another CMS like Forestry.

Let us know about your progress.

2 Likes

Thank you very much indeed for this great walk-through! You are right that the different ways in which Netlify (or NetlifyCMS!), Github, and Hugo interact - which one does what - are far from trivial for a beginner, even for one who’s generally IT-competent!

Anyway, since unfortunately I have to finish with this site quite soon (and since half of the content is already there anyway), I think it’s maybe easier to try and “debug” my immediate confusions now, and I will upgrade my mental model of how websites work in about a month when I have more time :slight_smile:

Right now I am just wondering:

  1. Although the .md files in my /content/home/ have indeed been saved according to my edits, these content edits are not reflected when I open my site in a browser. I’ve always been “committing” directly to the master branch, thus I don’t think this is a problem of parallel versions, but maybe NetlifyCMS is just not properly instructed to rebuild the site with each commit?!

  2. How can I get NetlifyCMS to let me edit all the various widgets using its GUI? Right now the only “Collections” I see there, on the left hand side, are: Authors,Posts,Projects,Talks,Pages. These are probably the default ones in the template, but I found no place where to edit that list, and also add other widgets there (Experience, etc)

  3. What is the advantage of editing the source code locally and pushing it with git commands, as opposed to editing directly on the github website (as I’ve been doing), whereby every commit should go live immediately?

  4. I cannot anywhere in my github repository find text contained in the default content of these widgets, so clearly I was not updating content in the right place.

Thanks again!