Hugo Support? (And other non-react static site generators)

[budparr]

Hey Tina folks. I'm curious to know where we are with Hugo support. Thanks!

[logan-anderson]

Great question! This was answered in discord but I am going to post it here too for visibility

Hi @budparr! As Scott said, we're hoping to start some proof of concept work for Tina on non-Next.js sites very soon. The team and Forestry users love Hugo, so it probably makes sense that the first few prototypes work with it. The idea that's being developed right now is basically putting Tina in a single page application (or however the SSG prefers to bundle/include javascript) with content editing forms and content discovery generated from the Tina schema (https://tina.io/docs/schema/). It would feel similar to Forestry (with the remote admin - https://forestry.io/docs/editing/remote-admin/) but the editing experience should be much more customizable for those who wish to dip into the Tina javascript APIs/config. I'd love to share our progress on this with you as soon as there's something tangible!

When we have something tangible I will post it in this thread.

[budparr]

Thank you, @logan-anderson. I was under the impression that that work had started some time ago and was more interested in where we are now. Any time frame?

[budparr]

oh, sorry. I understand you're using Discord instead of the discussions here and I see more answers there.

[logan-anderson]

We we try to have more "Real time" discussions in discord and more "long term" questions in Github Discussions.

In terms of a time frame we are looking to have some experimental (working but subject to change) in the first half of 2022 (Again this is a rough timeline).

In terms of process made. We are currently making an a TinaAdmin This will likely be the basis for the work with getting non-react static site generators using Tina.

Here is the PR of that latest work where you can find a video of what that might look like.

If you want to dig around. Here is a list of the PRs so far in this work. There may be other short video clips of what this might look like. But in terms of Something to play around with yourself we don't have anything yet unfortunately but will update you when we do.

[mitchmac]

@Enigmatical - I think reliance on Next.js routing would be one of the big blockers of this at the moment using Tina Admin? Are there any other big pieces that would need to be changed so that Tina Admin could be dropped into a non-Next.js site?

[Enigmatical]

Forgive my lack of knowledge about Hugo, but TinaAdmin does not actually utilize any Next.js concepts (outside of the wildcard route that I assume any generator would have).

Internally, TinaAdmin uses react-router v5. If you think of TinaAdmin as a sort of SPA, it only needs to be served by the /admin route (because its internal routing relies on /admin - this is a requirement we hope to be rid of in the near future).

[logan-anderson]

Update 01/12/22

Hey everyone 👋 , we have done some very early and very experimental/POC exploratory work for using Tina with static site generators like hugo.

See the video below for what the final product looks like

https://www.loom.com/share/d9227b079c954eef991060001527b02a

---

First some caveats

• This might not work in production yet (welcome to try)
  • There is no live previews in production
• We do not have a story for "live" editing
• Our recommended way for using hugo + Tina will probably look a bit different
• If you want a solution that "Just works" this might not be it

Overview

To achieve this we have 3 servers running

• A vite dev server serving the Tina Admin interface running on http://localhost:3000
• A TinaCMS Local graphQL server running on http://localhost:4001
  • This server serves all of the content in the markdown files and is how tina-admin communicates with the file system.
  • This also insures data integrity from the content model defined in the .tina/schema.ts
• A hugo dev server that is watching for changes in the file system and updating

How it is done

The code can be found here which contains two projects. (they could be separate)

tina-admin

This is a simple react application build with vite that runs an admin interface for editing content. This admin interface can be hooked up to any TinaCMS graphQL server. In our case it will be a local server running in our huge-site.

To start the admin dashboard the following command can be run (assuming the code is cloned onto a local computer)

cd tina-admin
yarn install
yarn dev

hugo-site

I used hugo in this example because of its popularity in forestry but the same ideas should be applied to any static site generator.

In here you will also notice a package.json this is because the local tinaCMS graphQL server will be started from within our hugo app. Both the dev server and the TinaCMS server will be running at the same time and to do this we could use two terminals but the TinaCMS server command allows us to run a subprocess.

So the package.json will look something like this.

{

  "scripts": {
    "dev": "yarn tinacms server:start -c\"hugo server -D\""
  },
  "dependencies": {
    "@tinacms/cli": "^0.59.0"
  }

So if the following commands are run

cd hugo-site
yarn install
yarn dev

This will install all the TinaCMS CLI and run the TinaCMS server along side the hugo dev server

Now we can edit the content on http://localhost:3000 and see the changes on the hugo dev server on http://localhost:1313

Further details

If anyone wants further instructions/questions feel free to replay to this thread or DM me in our community discord

[jamespohalloran]

Thanks for the helpful POC and video @logan-anderson !

I'm curious if people have thoughts on a good promoted pattern for deploying the admin.

A few assumptions:

• The .tina directory needs to live alongside the Hugo site with the content directory (For Tina Cloud to work)
• The CMS views also need to live in the same repo as the Hugo site, since the schema (soon) needs to be passed into the CMS' Tina wrapper.

A few options I can think of:

Monorepo setup:

One sub-directory contains the Hugo site. It exports the schema, which gets consumed by another sub-package containing the admin.
Both the sub-packages for the admin, and the Hugo site are deployed separately through Netlify/Vercel's monorepo support.

Monolithic setup:

Let the user setup 2 deployments for the same repo, each with different build configurations.
E.g, the dev might set up a Netlify project for the repo to build the Hugo site, and a Vercel project to build the admin. (Seems a bit clunky).

The Tina admin gets built into the Hugo site's /static or /public directory.

We might be able to make this easier with the use of Hugo modules (so link the built files to the /static directory), although I don't know how easily this approach would work for other SSGs?

Tina.io powered hosting

@logan-anderson brought this idea up. We could supply some hosting functionality for deploying the pre-built admin (similar to deploying a Sanity admin, or a Storybook admin).
Likely the most-effort of these solutions for us, but maybe the most seamless solution for the user.
One downside is that any sites with contextual-editing wouldn't be able take advantage of this.

[kldavis4]

@jamespohalloran the hosted solution is interesting wondering also if it would be the most framework agnostic

[jamespohalloran]

EDIT: This has all been moved over to a guide: https://tina.io/guides/tinacms/non-react-based-ssg/guide/

ORIGINAL:

I riffed off of @logan-anderson 's vite app POC, and added a little bit of a helper / guide for setting it up on an existing Hugo site.
Related to this post above, for deployment, to quickly get it working, the guide uses the approach of building the tina admin in the /static directory.

Also, I think there are lots of little things we could do to make this setup easier, but this should work for a basic MVP to get started.

Full walkthrough: https://www.loom.com/share/1a50dbfb76b844d29eed27001d93a9c4

(MVP) Adding Tina to Hugo Guide

Tina Scaffolding Setup

To setup the tina scaffolding in your Hugo project...

From within your Hugo root directory, run:

npx hygen init repo tinalabs/ssg-admin

Now we'll create the node configuration, to run the GraphQL API locally.

Run:

touch package.json

enter the following values into the newly generated package.json:

{
	"name": "hugo-site",
	"version": "1.0.0",
	"description": "",
	"main": "index.js",
	"scripts": {
		"dev": "yarn tinacms server:start"
	},
	"keywords": [],
	"author": "",
	"license": "ISC",
	"dependencies": {
		"@tinacms/cli": "^0.60.11"
	}
}

Add the node_modules directory to the .gitignore

echo "node_modules/" >> .gitignore

Now you can install the new dependencies with

yarn install

Now let's test that the content api is running correctly by running

yarn dev

You should be able to browse the content api's dummy content, by going to:
http://localhost:4001/altair

Running the Tina admin:

Now, in a new tab, let's run the Tina admin locally with:

cd tina-admin
yarn install
yarn dev

You should from here be able to edit your site's content from the editor. For help using the editor, checkout our docs

Note: To run this locally, you will need to be running the GraphQL server from the previous step.

Model your content

Out of the box, there is a content model created for a "dummy-post". You will want to checkout Tina's content modelling docs, so that you can edit the content within your Hugo site.

Deploying the admin

Step 1) Push your repo to git

Push your repo up to git, along its new tina configuration.

Step 2) Setup a Tina Cloud project

Checkout our Tina Cloud docs for help creating a Tina Cloud project

Step 3) Connect the project ID

In /tina-admin/src/App.tsx, set the following properties:

const clientId="<YOUR-TINA-PROJECT-ID-GOES-HERE>"
const branch = "<YOUR-BRANCH-HERE>"

where <YOUR-TINA-PROJECT-ID-GOES-HERE> is replaced by your client-id from your new TIna Cloud project.

Step 4) Build the admin for prod

Build the site locally with

  cd tina-admin && yarn build

This will output Tina's static admin page to the site's static directory.

Once that is built, push everything up to git (including the new built admin)

Step 5) Edit in production

When everything has redeployed, you should be able to enter edit-mode at:
<your-site-url>/admin

__Note: Anytime your admin is updated, (E.g, changing the clientId or branch). you will need to rebuild it locally and re-push it to git).

[CamilleScholtz]

I'm getting the following error upon clicking a collection:

Error] GetCollection failed: Unable to fetch, errors: Unable to find record 'content/artikelen/10-redenen-waarom-liberalisme-mensen-ongelukkig-maakt/thumb.webp' in Github Repository: 'onodera-punpun/Reactionair.nl[/]', Ref: 'main'

I assume that this is because I have webp images in my posts directories? Could these not be ignores, or possible the path variable be extended to allow for wildcards: path: 'content/artikelen/*/*.md'?

[jamespohalloran]

Right yeah currently, a collection's path generally needs to be a single file type or issues can pop up. We have a fix for this planned in our current sprint: #2703 so this should be handled better soon.

[CamilleScholtz]

It seems this issue is closed now! Could the guide be updated on how to use this version, or is it not compatible yet?

EDIT: alright, got it working, using the newest version of all Tina packages! Though 'Please wait, Tina is loading data...' is taking quite a while, is this normal?

[CamilleScholtz]

Another little point, I can't get the Datetime type to work, X1 is not a function. (In 'X1(e,t,n.strictParsing)', 'X1' is an instance of Object), where X1 is an a minified mention$3.

[jamespohalloran]

We can take a look into that! Just to keep this thread focused on the Hugo support, Would you mind creating an issue for this separate issue and proving a snippet of your formatted date, and any custom component in your schema.
https://github.com/tinacms/tinacms/issues/new?assignees=&labels=bug&template=bug-report.md

Also, curious if you can reproduce it in our playground

[jamespohalloran]

Just want to provide an update on this thread, as it's frequently asked in our Discord community:

We are close to releasing an update to Tina that will allow it to natively work on non-React sites (in "CMS-only mode"). This guide will soon be phased out and replaced with the much more streamlined solution

[redzimskidev]

Hello, is there any ETA? I'm looking at developing a blog using Netlify CMS, would love to start with Tina instead. Is there going to be an upgrade guide if I follow the current one?

[hrvstr]

What does "CMS-only mode" mean exactly? I am looking for a landing page CMS which means editing existing JSON files instead of creating Markdown files for a blog.

[jamespohalloran]

What does "CMS-only mode" mean exactly? I am looking for a landing page CMS which means editing existing JSON files instead of creating Markdown files for a blog.

The "CMS-only mode" is referring being able to edit with Tina, but without the contextual editing: https://tina.io/docs/using-tina-editor/

i.e: Your editors won't have a live-updating preview of the site, but they can use a nice editor, rather than writing markdown.

[bedwardly-down]

I’m currently testing it out, but so far, using the discussion in this thread, I was able to get a basic Tina instance to work with Hexo, another SSG built in JS that is pretty similar to Hugo but not as popular. I can’t wait for the new release to come out.

I also want to say thanks for making this super easy to figure out overall. I wanted a CMS for my blogs and found Tina only a few hours ago.

[redzimskidev]

Hi, really looking forward to trying out Tina with Hugo in the new setup. Is there any PR I could track? Maybe I could help out with some beta testing or docs?

[jeffsee55]

We've released a new static init command to help get started. Please let us know what you think!

https://tina.io/guides/tinacms/non-react-based-ssg/guide/

[CamilleScholtz]

Using yarn as the package manager at least, I have to manually install 'styled-components'.

[lsze]

Hugo and other SSGs such as 11ty allow for .json files as data collections, great for things like menus or storing site settings. Forestry had beautiful support for this but so far in my experiments Tina seems to require schema > collections > path be a folder. Do you plan on supporting single data files as collections? Or is there a workaround I missed?

[jeffsee55]

@lsze great question, it's not something we're actively working on yet definitely planning!

[yevarizhko]

2 years later. I was looking into that myself. The work around is to split single .yaml file into multiple and place them in a subfolder. Tina is able to recognize those small files. Then you need to parse that folder with Hugo. Here how code snippet will look for services folder within data folder full of .yaml files (their filenames don't matter to Hugo):

{{ range $service := .Site.Data.services }}
    <a href="{{ .url }}">
      <div>
        <h3>{{ .title }}</h3>
        <span>{{ .description }}</span>
      </div>
    </a>
{{ end }}

Example of one of the files in data/services folder:

title: Design
description: Designing logo and websites
url: /design

But still looking for ability to setup Tina to use one .yaml file.

[tomoyanonymous]

Hi, the static init command worked for my website. I think it works mostly the same as forestry.io.

The validation of markdown parser looks a bit more strict than it of forestry. Bodies of many articles returned parse errors. For example, they contain slash/ in the text, raw HTML tags and etc.

Also, I use Hugo's Page Resource which places image files relative to the markdown files for asset management. This is used for generating thumbnails of the images used in the article for each article.
So, when I use the "image" field for frontmatter, it only refers to the media root directory. (This is the same as forestry)
Is there any way to customize that allows referring page resources for the "image" field?

[jeffsee55]

Thanks for the info, one of the challenges here would be allowing editors to browser images, if image a.jpg is only intended to be used for first-post, it almost seems like a chicken and egg situation. Where did the editor get image a.jpg from if it's not in the centralized static/images? If image a.jpg was in static/images/a.jpg, would it be beneficial to hugo users to do a symlink to first-post/images/a.jpg?

[tomoyanonymous]

Indeed... If the article is going to be newly created, the image uploaded through tina needs to be stored in some temporary directory. When the article is submitted (= just before some commit happens), the image should be moved, and the link should be updated.
Then, when the user edits the existing article, tina just needs to refer to relative paths to the article.
Essentially, Hugo can use images in a deeply nested directory like content/post/first-post/images/hoge/fuga/1/a.jpg, but if the images are uploaded through tina, it will be enough to put them in the same directory as the markdown file of the article.

Note that if the website uses Page Resource, still some images which are commonly used in the website(logo or default OGP images) will be in static folder. So image chooser needs to find images from both static/ and the relative path to the article.

Using symlink in hugo may cause different behavior between the local and the deploy environment.
https://discourse.gohugo.io/t/quick-tip-for-symbolic-links/14185

[jeffsee55]

When the article is submitted (= just before some commit happens), the image should be moved, and the link should be updated.

If the image is moved, that would mean it can't be discovered for use by another editor, that seems like it might lead to some confusion if images are effectively being removed seemingly at random.

What would you say is the biggest upside to page bundles? I wonder if Tina's responsibilities are at odds with Hugo's in this case, both are trying to make content easier to manage. At the end of the day, what would you say is the main benefit to page bundles?

[h-enk]

At the end of the day, what would you say is the main benefit to page bundles?

I'd say, keeping your content — including images — organized, grouped by
/related to page.

Could one do that, that easily in the assets or static folder?

[tomoyanonymous]

What would you say is the biggest upside to page bundles? I wonder if Tina's responsibilities are at odds with Hugo's in this case, both are trying to make content easier to manage. At the end of the day, what would you say is the main benefit to page bundles?

The most likely example is the theme with an image gallery of the pics used in each article.
Hugo's template system can not generate a list of images used in the article from the source file. The only way to do that is to enumerate every image file from page resources.
https://gohugo.io/content-management/image-processing/

I use the page resources for just generating thumbnails, not for the gallery. but this is because my custom template is now relatively old. Now hugo has Render hook, a more suitable system to generate thumbnails.

Migrating all images on my existing site is gonna be hard work, so this would be the "biggest downside for not using page bundle".

[leafarafael]

Can we use tinacms build && hugo --minify in Github Action?

[jeffsee55]

I don't see any reason that this wouldn't work. Have you tried it?

[leafarafael]

Hi @jeffsee55
I actually posted my issue here:
#3586 (reply in thread)
Maybe can you take a look, I think I'm missing something here.