Local install not working after following instructions

[cjyabraham]

I'm confused by how this hugo site has been reconfigured. Nevertheless I followed the instructions in the README to install it on my macos laptop. When I open my local instance after this, it is missing some pages in the nav. For example, the Publications sidebar looks like this, missing its subpages:

I'm trying to add some new pages to the Publications so, following the instructions, I add them to the /publications/ directory. The new pages don't show in the sidebar. How is that supposed to work?

I tried re-running make deps and I then got this in my terminal.

I originally set up this site and it used to be a straightforward hugo site and was configured consistently with all the other CNCF Hugo subsites. What was the motivation for changing it to this configuration and how can I get it to work?

CCing @brandtkeller as he seemed to be the last to update the REAMDE instructions.

[brandtkeller]

Appreciate the intent here can calling out gaps with regards to building locally. The website is still a work in progress - but the goal has been to publish more of the TAG documentation/publications and other community material without needing explicit knowledge of the website. It also allows the

As you pointed out - the website readme contains the steps to get the website up and running locally provided you have the required tooling.

Looking at your gist and your description I could see one of two potential issues:

1. multiple make deps executions may not be ironed-out yet. I would run a make clean between each make deps execution.
2. depending on your system, you may not have gnu-sed installed and the default macos sed may not support the commands used in the Makefile - see here

If neither of those resolve the problem please let me know!

[cjyabraham]

It seems like replacing the MacOS sed with the gnu-sed solved one of my problems. Should this be called out in the README for everyone on MacOS? Is there a way to configure things so that I don't have to do this system-wide because replacing a tool like this would possibly cause problems on other projects I'm working on?

How do I get the live reload to work? npm run start used to automatically show any changes I make to hugo content files but it doesn't seem to be working in this configuration? Do I have to do a make clean then make deps then npm run serve after every edit?

How do I get a standard listing page to work inside a new directory? In Hugo I would create a _index.md file but that doesn't seem to be working now.

[brandtkeller]

It seems like replacing the MacOS sed with the gnu-sed solved one of my problems. Should this be called out in the README for everyone on MacOS? Is there a way to configure things so that I don't have to do this system-wide because replacing a tool like this would possibly cause problems on other projects I'm working on?

That is a great point - there is a process/workflow historically which worked well for docker/docker compose that we very well should revisit. Any additions to the website/README.md towards macos development are more than welcome!

How do I get the live reload to work? npm run start used to automatically show any changes I make to hugo content files but it doesn't seem to be working in this configuration? Do I have to do a make clean then make deps then npm run start after every edit?

Live reload is working on my installation currently with npm run serve. If I make an edit to anything under website/content and save the file I get an automatic reload. What behavior are you seeing?

How do I get a standard listing page to work inside a new directory? In Hugo I would create a _index.md file but that doesn't seem to be working now.

You should not need to create an _index.md file. Rather there are a subset of directories called out here. If you are looking to create an item under that page it should simply be an additional markdown file under one of those directories or a sub-directory.

Overall we still have much more work to do and would love the input and feedback. Looking over the other CNCF TAG websites, I don't see any the reflect the intent to produce/expose as much content as we have both in our repository but also making that published to the website.

I am hopeful moving forward we can address gaps in website development with an idea that it remains almost invisible to those who only need to interact with the repository contents itself.

[cjyabraham]

How do I get the live reload to work? npm run start used to automatically show any changes I make to hugo content files but it doesn't seem to be working in this configuration? Do I have to do a make clean then make deps then npm run start after every edit?

Live reload is working on my installation currently with npm run serve. If I make an edit to anything under website/content and save the file I get an automatic reload. What behavior are you seeing?

I thought in your new setup, edits are to be made to the root content directories and not the files in website/content? That's what I gathered from your README statement "Add content by adding Markdown files to directories identified in the Makefile include list." Live reloads do not seem to work for edits to these root content files.

How do I get a standard listing page to work inside a new directory? In Hugo I would create a _index.md file but that doesn't seem to be working now.

You should not need to create an _index.md file. Rather there are a subset of directories called out here. If you are looking to create an item under that page it should simply be an additional markdown file under one of those directories or a sub-directory.

I'm looking to create a collection of items under one of the root directories, so I was going to use the list template to list the sub items. This would normally use the standard Hugo list.html template. It seems this no longer works.

Overall we still have much more work to do and would love the input and feedback. Looking over the other CNCF TAG websites, I don't see any the reflect the intent to produce/expose as much content as we have both in our repository but also making that published to the website.

If there is still a lot of work to do, would it be better to work on this in a branch rather than have this committed to main?

So far this seems more idiosyncratic and cumbersome than the way Hugo does things. It has a more complex set of dev dependencies (at least on MacOS) and has disabled some of the Hugo conveniences (live reload, list templates, frontmatter metadata to fine-tune pieces of content, and perhaps more) Also, after running make deps, it pollutes the git changeset with a bunch of temporary files in website/content which I'm having to be careful not to accidentally check in.

What were the pain points with the standard Hugo setup? Of course, any website is going to have some kind of learning curve to edit content but I doubt it's possible to make it much simpler than Hugo is out-of-the-box, unless you want to use a full CMS like WordPress. Additionally, once someone learns the Hugo conventions, they will be able to edit all other similar sites, such as the many other Hugo sites in the CNCF ecosystem.

[brandtkeller]

I thought in your new setup, edits are to be made to the root content directories and not the files in website/content? That's what I gathered from your README statement "Add content by adding Markdown files to directories identified in the Makefile include list." Live reloads do not seem to work for edits to these root content files.

That is correct. Live reloading works for edits to files for temporary development purpose - but not for edits to the root content. Certainly a workflow that could use some refinement but I tend to experiment with the changes I want to make using the live-reload functionality and the temporary website content (after running make deps) and once I have my preferred changes ready - I will transfer those out to the root of the project accordingly - make clean && make deps and npm run serve to validate changes - make clean to remove temporary files and commit.

I'm looking to create a collection of items under one of the root directories, so I was going to use the list template to list the sub items. This would normally use the standard Hugo list.html template. It seems this no longer works.

This would be a great issue to file as this needs to be investigated more.

if there is still a lot of work to do, would it be better to work on this in a branch rather than have this committed to main?

So far this seems more idiosyncratic and cumbersome than the way Hugo does things. It has a more complex set of dev dependencies (at least on MacOS) and has disabled some of the Hugo conveniences (live reload, list templates, frontmatter metadata to fine-tune pieces of content, and perhaps more) Also, after running make deps, it pollutes the git changeset with a bunch of temporary files in website/content which I'm having to be careful not to accidentally check in.

What were the pain points with the standard Hugo setup? Of course, any website is going to have some kind of learning curve to edit content but I doubt it's possible to make it much simpler than Hugo is out-of-the-box, unless you want to use a full CMS like WordPress. Additionally, once someone learns the Hugo conventions, they will be able to edit all other similar sites, such as the many other Hugo sites in the CNCF ecosystem.

I am just weighing in with my opinions based on latest website iterations (a chair or TL may have a more official stance). In my opinion I'd like to see a rework of the underlying website infrastructure in a way that maintains parity with the current breadth of content published. I hope this would resolve some of the concerns that you have raised above and I may write an issue shortly for that proposal and include these as items to consider.

The main delineation between TAG Security and the other TAG websites is that the content published to the website is not statically contained within the website directory - rather we are pulling source of truth from content that lives in other locations for other purposes. These artifacts should continue to be maintained and we were experimenting with the concept of keeping them separate from the website but syncing them as the website was built.

[eddie-knight]

Please reopen this issue if any more support is needed.

If we can convert any of this into action items for improvement, lets do that in a new issue.