TC Cazy Cover Photo
TC Cazy Avatar

TC Cazy

Multipassionate Web Creator, and Community Builder.

Follow

Share this Profile

Topics

Post

Zite - Carrd templates

Drrac has rebranded to Zite, check out our new templates!

Fast Sites and Landing Pages | Carrd

Resources for Carrd creating websites and Carrd templates!

Read More
Hide
Saved to
Fast Sites and Landing pages
8 months ago
8 months ago

The Internet rewards unique people. Find your unique combination of skills, interests, and personality traits. I call this a Personal Monopoly. Become the only person in the world who does what you do. Then, tell the world by sharing your knowledge. https://t.co/FcvdiEjo5Q

David Perell
8 months ago
8 months ago

← Blog

3 min read

In this post, I will dive into the details and everything you need to know on building a website in Notion. Let's get started.

Planning and wireframing

Notion blocks are flexible to drag and drop across the canvas. Honestly, I don't see a need to plan or wireframe your website elsewhere. However, if you are looking to build a multi-page full fledged website, here are some design tools to check out.

Figma

Sketch

Call-to-action Buttons

Creating a button for your Notion website can be as simple as using a callout block or pasting a link over the text. If you are looking for an actual looking buttons, Indify got you covered. And yes is free.

After customising the button at Indify.co , simply copy the link then paste into Notion and choose embed. If Indify doesn't work for you for any reasons, you can also check out an alternative call-to-action button generator called butn.one .

Forms and Lead Capture

Similar to buttons, there's a form-building tool to build and customise your form that can later be embeded into your Notion website.

Head over to Tally.so and the form builder will appear. You can create a form from scratch or use one of the pre-made templates . There's all kinds of blocks to create the form you need, including text input, email input, multiple choice, checkboxes, linear scale and even payment.

Tally does a great job explaining the details in building a form from scratch, so I'll leave it to them here . One thing I can promise is that it is simple to use and completely free to try out.

Custom Domains

Before I dive into the details into using a custom domain for your Notion website, I like to share a quick tip especially for those using the Pro Plan in Notion. Learn how to host your website on a simple notion.site domain below.

Public Home Page

  1. On desktop, click Settings & members in the left-hand sidebar.
  2. Go to Settings
  3. If you’re an admin in the workspace, you’ll see the option to change your domain and select a page as your public home page right below your workspace icon:
image

Let's move on to talk about custom domains for Notion. One method to use a custom domain without any 3rd party platforms is to redirect the domain name to the URL of your Notion page. This can be done via the domain provider website you use to purchase your domain name.

Another method I recommend and use would be Super . If you did not know, this blog is hosted by Super. Besides having a custom domain, you get access to powerful integrations, better SEO, custom navigation bars, custom fonts and more. If you know a little HTML or CSS, you can level up your website design further, and bring more possibilities to your Notion website.

Not to worry if you're not a fan of coding, Super has as growing collection of themes and templates you can choose from to customise your webste with no code required. You can learn more about Super here .

Alternatively, you can also use Potion.so to customise your website.

Analytics

If you're not ready to invest in a domain name but need insights about your Notion pages, this section is for you. I want to share with you a tool called Notionlytics, which makes it easy for you to embed Google Analytics or Facebook Pixel tracker into your Notion page.

In an overview, Notionlytics generates a snippet for you to embed into your page.

Once you embed the snippet into your page it will start collecting analytics.

If this is something you need, you can check out and learn more about Notionlytics here .

And that is how you build a website in Notion. Before you close this blog and go create that amazing website of yours, I thought to leave some links to illustrations perfect for your Notion websites.

Resources

Open Doodles

Open Peeps

Indian Doodle Illustration Pack

skribbl

Illustrations Vol.1

Notion Styled Avatar

Productivity | Notion
How to create a Website using Notion

Read More
Hide
Saved to
Productivity
8 months ago
8 months ago

What’s up my Carrd Builders!

Finally! One place where you can find information and resources for Carrd. 🛑 To help you navigate or give some insight, these

purple

blocks have been added throughout the guide.

Ready to dive in?

📒

Browse Resources

Finally! One place where you can find information and resources for Carrd.To help you navigate or give some insight, theseblocks have been added throughout the guide.

Fast Site building and landing pages | Carrd

learning material
template marketplaces
widgets / embeds
payment processing

Read More
Hide

Gutenberg and Decoupled Applications

In this article I want to dive into the current state of Gutenberg and WPGraphQL.

This is a technical article about using Gutenberg blocks in the context of decoupled / headless / API-driven WordPress, and makes the assumption that you already know what Gutenberg is and have some general understanding of how it works.

TL;DR

Client-server contracts around the shape of data is fundamental to achieving “separation of concerns”, a pillar of modular and decoupled application development.

While much of WordPress was built with decoupling in mind , the WP REST API and Gutenberg were not .

As a result, decoupled application developers interacting with WordPress are limited in what they can achieve .

With the growing demand for headless WordPress , this is a key limitation that will hamper growth.

Fortunately, even with the limitations , there are ways forward. In this article I walk through 3 approaches you can implement to use Gutenberg in decoupled applications today, tradeoffs included, and propose a plan to make the future of Gutenberg for decoupled applications a better one.

Replacing my door lock

I recently replaced the lock on the front door of my house.

I ordered the lock from an online retailer. I was able to select a specific brand of lock in a specific color.

When the lock arrived and I opened the package, it was the same brand and color that I ordered. It wasn’t just any random lock, it was the one that I agreed to pay for, and the online retailer agreed to mail me.

I was able install the lock without any surprises. I didn’t have to drill any new holes in my door. The new lock fit the hole in my door that I removed the old lock from.

The new lock wasn’t made by the same manufacturer that made the door, and yet, the lock installed on my door just fine. In fact, there were at least 30 different locks from a variety of manufacturers that I could have selected that all would have worked in my door without any complications.

Decoupled systems

This wasn’t really a story about doors and locks. It’s a story about decoupled systems, and the contracts, or agreements, that make them work.

And its intent is to help frame what I’m talking about with using WordPress, and specifically Gutenberg, in decoupled contexts.

In order for decoupled systems to work well, whether it’s doors and door locks, or WordPress and a decoupled JavaScript application, there needs to be some sort of agreement between the different parts of the system.

In the case of door and lock manufacturers, it’s an agreement over the size and positioning of the holes in the door.

Diagram showing measurements for a door lock hole

Door manufacturers can build doors at their leisure and lock manufacturers at theirs, and when the time comes to bring them together, they work without issue because both parties are adhering to an agreement.

In the case of e-commerce, there are agreements about what a consumer purchases and what should be delivered. In my case, the online store provided a list of locks that were available to purchase. I selected a specific lock, paid for it, and in response I received the lock we agreed to, in exchange for my payment.

Decoupled tech, decoupled teams

When WPGraphQL first started, I was working at a newspaper that had a CMS team that focused on WordPress, a Native Mobile team that focused on the iOS and Android applications, a Data Warehouse team that collected various data from the organization and a Print team that took the data from WordPress and prepared it for Print.

WordPress was the entry point for content creators to write content, but the web was only one of many channels where content was being used.

Not only was the technology decoupled (PHP for the CMS, React Native for mobile apps, Python for Data warehousing and some legacy system I forget the name of for print), but the teams were also decoupled.

The only team that really needed to understand WordPress was the CMS team. The other teams were able to use WPGraphQL Schema Introspection to build tools for their teams using data from WordPress, without needing to understand anything about PHP or WordPress under the hood.

Much like door and lock manufacturers don’t need to be experts at what the other is building, WPGraphQL’s schema served as the contract, enabling many different teams to use WordPress data when, and how, they needed.

WPGraphQL served as the contract between the CMS team and the other teams as well as WordPress the system and the other team’s decoupled systems.

WordPress contracts

For WordPress, one of the common contracts, or agreements established between multiple systems (such as plugins, themes, and WordPress core) comes in the form of registries.

WordPress has registries for Post Types, Taxonomies, Settings, Meta and more.

The register_post_type function has more than 30 options that can be configured to define the contract between the Post Type existing and how WordPress core and decoupled systems (namely plugins and themes) should interact with it.

The register_taxonomy , register_meta , register_setting , register_sidebar and other register_* functions in WordPress serve a similar purpose. They allow for a contract to be established so that many different systems can work with WordPress in an agreed upon way.

These registries serve as a contract between WordPress core and decoupled systems (themes and plugins) that can work with WordPress. Because these registries establish an agreement with how WordPress core will behave, plugins and themes can latch onto these registries and extend WordPress core in some powerful ways.

The decoupled (pluggable) architecture of WordPress is enabled by these contracts.

Image showing WordPress in the middle with the logos for ElasticPress, WordPress SEO by Yoast, WPGraphQL and Advanced Custom Fields around it.
WordPress registries enable plugins to iterate outside of WordPress core

Registering a new post type to WordPress can get you a UI in the WordPress dashboard, but it can also get your content indexed to Elastic Search via ElasticPress , powerful SEO tools from WordPress SEO , custom admin functionality from Advanced Custom Fields , and API access via WPGraphQL .

If the next release of WordPress started hiding the UI for all post types that were registered with show_ui => true , or stopped allowing plugins from reading the post type registry, there would likely be a bug (or hundreds) reported on Trac , (and Twitter, and Slack, etc), as that would mean WordPress was breaking the established contract.

The client/server contract

Like we discussed earlier, decoupled systems need some sort of shared agreement in order to work well together. It doesn’t have to be a GraphQL API, but it has to be something.

For WordPress, this comes in the form of APIs.

WordPress core has 2 built-in APIs that enable decoupled applications to interact with WordPress data, XML-RPC and the WP REST API .

And, of course, there’s yours truly, WPGraphQL , a free open-source WordPress plugin that provides an extendable GraphQL schema and API for any WordPress site.

Blocks representing REST, GraphQL and RPC API on top of a block representing the Authorization and Business logic layers of WordPress, and at the bottom is a block representing the Persistence Layer (MySQL).
Diagram of the WordPress server + API setup

In order for decoupled applications, such as Gatsby , NextJS , Frontity , native mobile applications or others, to work with WordPress, the APIs must establish a contract that WordPress and the decoupled application can both work against.

The WP REST API provides a Schema

The WordPress REST API provides a Schema that acts as this contract. The Schema is introspect-able, allowing remote systems to see what’s available before asking for the data.

This is a good thing!

But the Schema is not enforced

However, the WP REST API doesn’t enforce the Schema.

WordPress plugins that extend the WP REST API Schema can add fields to the API without defining what data will be returned in the REST API Schema. Or, they can register fields that return “object” as a wildcard catch-all.

This is a bad thing!

Decoupled teams and applications cannot reliably use the WordPress REST API if it doesn’t enforce any type of contract.

Optional Schema and wildcard return types

Plugins such as the Advanced Custom Fields to REST API add a single “acf” field to the REST endpoints and declare in the WP REST API that the field will return “an object”.

We can see this if we introspect the WP REST API of a WordPress install with this plugin active:

Screenshot showing the Introspection of the ACF to REST API Schema definition

This means that decoupled applications, and the teams building them, have no way to predict what data this field will ever return. This also means that even if a decoupled application does manage to get built, it could break at any time, because there’s no contract agreed to between the client and the server. The WordPress server can return anything at anytime .

Unpredictable data is frustrating for API consumers

With the field defined as “object” the data returned can be different from page to page, post to post, user to user, and so on. There’s no predictable way decoupled application developers can prepare for the data the API will return.

This would be like me trying to purchase that door lock, but instead of the website showing me a list of door locks with specific colors to chose from, I was just given one “product” as the option to purchase.

The “product” might be a hat or some new sunglasses, or if I’m really lucky, it might be a door lock. I don’t have any way of knowing what the “product” is, until I receive it.

As an e-commerce consumer, this is not helpful.

And as a decoupled application developer, this type of API is frustrating.

Decoupled systems don’t work well if part of the equation is to “just guess”.

GraphQL enforces Schema and Strong Types

WPGraphQL, on the other hand, enforces a strongly Typed Schema. There is no option to extend the WPGraphQL API without describing the type of data the API will return. Additionally, there is no “wildcard” type.

A plugin cannot register a field to the WPGraphQL Schema that returns a door lock on one request, and sunglasses or a hat on the next request.

To extend WPGraphQL, plugins must register fields that declare a specific Type of data that will be returned. And this contract must be upheld.

This removes the “just guess” part of the equation.

Decoupled application developers always know what to expect.

Much like I, as an e-commerce consumer, was able to browse the list of door locks that were possible to purchase on the online store, decoupled application developers can use a tool such as GraphiQL to browse the GraphQL Schema and see what Types and Fields are available to query from the GraphQL API.

The screenshot below shows GraphiQL being used to explore a GraphQL Schema. The screenshot shows the type named “Post” in the GraphQL Schema with a field named “slug” which declares that it will return a String.

Screenshot of GraphiQL showing the “slug” field on the “Post” type.

Application developers can take the information they get from the Schema and construct queries that are now predictable.

And the GraphQL Schema serves as the contract between the server and the client application, ensuring that the server will return the data in the same shape the client was promised.

Just like I received the specific door lock matching the brand and color that I specified in my order, client applications can specify the Types and Fields they require with a GraphQL Query, and the response will match what was asked for.

In the example below, the GraphQL Query asks for a Post and the “slug” field, which we can see in the Schema that it will return a String. And in response to this query, the GraphQL server will provide just what was asked for.

The “just guess” part of the server/client equation is eliminated.

Example GraphQL Query & Response

query {
post( id: 1, idType: DATABASE_ID ) {
slug
}
}
{
"data": {
"post": {
"slug": "hello-world",
},
},
}
Screenshot showing a GraphQL Query and Response in the GraphiQL IDE

The Gutenberg block registry

Now that we’re on the same page about contracts between decoupled systems and how WPGraphQL provides a contract between the WordPress server and client applications, let’s move on to discuss Gutenberg more specifically.

Early integration with WPGraphQL

Gutenberg as a concept was fascinating to me early on. Like many others, I saw the potential for this block-based editor to impact WordPress users and the WordPress ecosystem greatly, WPGraphQL included.

I explored exposing Gutenberg blocks as queryable data in WPGraphQL as far back as June 2017:

Challenges and the current state of Gutenberg

While a basic initial integration was straightforward, I ran into roadblocks quickly.

Gutenberg didn’t have a server-side registry for blocks. At this time, all blocks in Gutenberg were fully registered in JavaScript, which is not executed or understood by the WordPress server.

This means that unlike Post Types, Taxonomies, Meta, Sidebars, Settings, and other constructs that make up WordPress, Gutenberg blocks don’t adhere to any type of contract with the WordPress server.

This means that the WordPress server knows nothing about blocks. There are no agreements between Gutenberg blocks and other systems in WordPress, or systems trying to interact with WordPress via APIs.

Blocks were practically non-existent as far as the application layer of WordPress was concerned.

There were no WP-CLI commands to create, update, delete or list blocks. No WP REST API Schema or endpoints for blocks. No XML-RPC methods for blocks. And no way to expose blocks to WPGraphQL .

Without any kind of agreement between the WordPress server and the Gutenberg JavaScript application, the WordPress server can’t interact with blocks in meaningful ways.

For example, the WordPress server cannot validate user input on Gutenberg blocks. Data that users input into the fields in Gutenberg blocks is trusted without question and saved to the database without the server having final say. This is a dangerous precedent, especially as Gutenberg is moving outside of editing Post content and into other parts of full-site editing. As far as I know, the lack of block input validation by the WordPress server is still a problem today.

Anyway, without the WordPress server having any knowledge of blocks, WPGraphQL also could not provide a meaningful integration with Gutenberg.

I was sad, because I was optimistic that this integration could lead to some really great innovations for decoupled applications.

Shortly after my tweet above and running into roadblocks, I raised these concerns with the Gutenberg team on Twitter and Slack. The Gutenberg team asked me to post my thoughts in a Gutenberg Github issue, which I did at length . While my comments received a lot of positive emoji reactions from the community. Unfortunately the issue has been closed with many of the concerns outstanding.

Months later I also voiced similar concerns on the Make WordPress post about Gutenberg and Mobile, pointing out that without a proper server registry and API, decoupled applications, such as the WordPress native mobile application, won’t be able to support Custom Blocks, or even per-site adjustments to core blocks.

As of today, my understanding is that the WordPress native mobile applications still do not support custom blocks or adjustments to core blocks, making the App nearly useless for sites that have adopted Gutenberg.

Even with the limitations of Gutenberg, the headless WordPress community has been determined to use Gutenberg with decoupled applications.

Three approaches to using Gutenberg in decoupled applications, today

Below are some of the different approaches, including tradeoffs, that you can implement today to start using Gutenberg in decoupled applications.

Gutenberg blocks as HTML

I believe the fastest way to get started using Gutenberg in decoupled applications today, is to query the “content” field from WPGraphQL (or the WP REST API, if it’s still your flavor).

This is the approach that Frontity is using .

This is also the approach I’m using for WPGraphQL.com, which is in use on this very blog post you’re reading right now.

This post is written in Gutenberg, queried by Gatsby using WPGraphQL, and rendered using React components!

Here’s how it works (and please don’t judge my hacky JavaScript skills 🙈):
  • The GraphQL Query in Gatsby gets the content ( see the code )
  • The content is passed through a parser ( see the code )
  • The parser converts standard HTML elements into the Chakra UI equivalent to play nice with theming ( see the code )
  • The parser also converts things like HTML for Twitter embeds, and `<code>` blocks into React components ( see the code )
    • This is how we get neat things like the Syntax highlighting and “copy” button on the code snippets

Tradeoff: Lack of Introspection, unpredictable data

While this is working for me and WPGraphQL.com, I can’t recommend it for everyone.

Using HTML as the API defeats much of the purpose of decoupled systems. In order to use the markup as an API, the developers of the decoupled application need to be able to predict all the markup that might come out of the editor.

Querying HTML and trying to predict all the markup to parse is like me ordering “product” at the store. At any time I (or other users of WordPress) could add blocks with markup that my parser doesn’t recognize and the consuming application might not work as intended.

Tradeoff: Missing data

Content creators can modify attributes of blocks, and Gutenberg saves these attributes as HTML comments in the post_content. But when the content is prepared for public use in WordPress themes, the WP REST API or WPGraphQL, the raw block attributes are not available, so a parser like the one I described will not have all the block data to work with.

Tradeoff: Undefined Types

To overcome the “missing data” issue, it’s possible to pass attributes from Gutenberg blocks as HTML data-attributes in the render_callback for blocks, as a way to get Gutenberg attributes passed from the editor to the rendered HTML and available for a parser to use, but even doing this leads to client applications not knowing what to expect, and leads to undefined Types as all data-attributes are strings, so mapping data-attributes to something like a React or Vue component is difficult and fragile with this method.

When to use

This approach works for me, because I personally control both sides of wpgraphql.com, what blocks are available in the WordPress install, what content is published, and the Gatsby consumer application that queries the content and renders the site. In the e-commerce analogy, I’m both the person ordering the “product” and the person fulfilling the order, so there are no surprises. I’m not working with different teams, or even different team members, and I’m the primary content creator.

For projects that have multiple team members, multiple authors, multiple teams and/or multi-channel distribution of content, I would not recommend this approach. And multi-team, I would argue, includes the team that builds the project, and the team that maintains it after it’s live, which in many agencies are different teams.

Gutenberg Object Plugin

In late 2018, Roy Sivan , a Senior JavaScript Engineer and recurring Happy Birthday wisher to Ben Meredith , released a plugin that exposed Gutenberg blocks to the WP REST API:

This plugin exposes Gutenberg block data to the WP REST API so that data saved to pages can be consumed as JSON objects.

Exposing Gutenberg data as JSON is what a lot of developers building decoupled applications want. They want to take the data in a structured form, and pass the data to React / Vue / Native components. This plugin gets things headed in the right direction!

Tradeoff: Lack of Introspection, unpredictable data

But, because of the lack of a server-side registry for Gutenberg blocks, and the non-enforced Schema of the WP REST API, this plugin also suffers from the “just guess” pattern for decoupled applications.

This plugin is unable to register blocks or fields to the WP REST API, so inspecting the Schema leaves decoupled application developers guessing.

If we Introspect the REST API Schema from this plugin and we can see that the Schema doesn’t provide any information to the decoupled application developer about what to expect.

Screenshot of the introspection of the Gutenberg Object Plugin REST endpoint

It’s like ordering a “product” from an e-commerce store. The endpoint can return anything at any time, and can change from page to page, request to request.

There’s no contract between the REST endpoints and the consumer application. There’s no scalable way for decoupled application developers to know what type of data the endpoints will return, now or in the future.

Tradeoff: Only available in REST

If you’re building headless applications using WPGraphQL, taking advantages of features that differentiate WPGraphQL from REST, you would not be able to use the GraphQL Objects plugin in your decoupled application without enduring additional pain points, in addition to the lack of introspection.

Caching clients such as Apollo would have to be customized to work with data from these endpoints, and still may not work well with the rest of the application that might be using GraphQL. Additionally, when using REST endpoints with related resources, it becomes the clients responsibility to determine how to map the various block endpoint data to the components that need the data. There’s no concept of coupling GraphQL Query Fragments with Components, like you can do with GraphQL.

When to use:

Again, if you are the developer controlling both sides, the WordPress server and the client application, this approach could work, at least while you’re building the application and the capabilities are fresh in your mind. But in general, this approach can cause some pain points that that might be difficult to identify and fix when things go wrong. For example, 6 months down the road, even the person that built the application will likely forget all the details, and when there’s a bug, and no contract between the applications to refer to, it can be hard to diagnose and fix.

Even when things break with GraphQL applications (and they do), the explicit nature of GraphQL Queries serve as a “documentation of intent” from the original application developer and can make it much easier for teams to diagnose, down to specific leaf fields, what is broken.

WPGraphQL for Gutenberg

In early 2019 Peter Pristas introduced the WPGraphQL for Gutenberg plugin.

The intent of this plugin is to expose Gutenberg blocks to the WPGraphQL Schema, so that decoupled application developers could use tools such as GraphiQL to inspect what blocks were possible to be queried from the API, and compose GraphQL Queries asking for specific fields of specific blocks that they wanted to support.

Now, content creators can publish content with Gutenberg, and decoupled application developers can introspect the Schema and construct queries asking for the specific blocks and fields their application supports.

Decoupled application developers can move at their own pace, independent from the developers and content creators working on the CMS. The decoupled application can specify which blocks are supported, and ask for the exact fields they need. Much like an e-commerce consumer can specify the specific color door lock they want to order from the store! The Schema serves as the contract between the server and the client. Clients can predictably ask for what they want, and get just that in response.

Creating a page

Content creators can use Gutenberg to create pages. In the example blow, we see a page in Gutenberg with a Paragraph block and an Image block.

Screenshot showing the Gutenberg editor with a paragraph and image block.
Screenshot showing the Gutenberg editor with a paragraph and image block.

Exploring the Schema

With the plugin installed and activated (for demo sake I have WPGraphQL v1.2.5 and WPGraphQL for Gutenberg v0.3.8 active), decoupled application developers can use GraphiQL to browse the Schema to see what Gutenberg Blocks are available to query and interact with.

Screenshot of GraphiQL showing Gutenberg Blocks
Screenshot of GraphiQL showing the CoreParagraphBlock and its fields

Querying the blocks

And using the Schema, developers can construct a query to ask for the blocks and fields that their application supports.

Here’s an example query:

{
post(id: 6, idType: DATABASE_ID) {
id
databaseId
title
blocks {
__typename
name
... on CoreImageBlock {
attributes {
... on CoreImageBlockAttributes {
url
alt
caption
}
}
}
... on CoreParagraphBlock {
attributes {
... on CoreParagraphBlockAttributes {
content
}
}
}
}
}
}

And the response:

You can see that the response includes the exact fields that were asked for. No surprises.

{
"data": {
"post": {
"id": "cG9zdDo2",
"databaseId": 6,
"title": "Test Gutenberg Post",
"blocks": [
{
"__typename": "CoreParagraphBlock",
"name": "core/paragraph",
"attributes": {
"content": "This is a paragraph"
}
},
{
"__typename": "CoreImageBlock",
"name": "core/image",
"attributes": {
"url": "http://wpgraphql.local/wp-content/uploads/2021/03/Screen-Shot-2021-03-04-at-12.11.53-PM-1024x490.png",
"alt": "Jason Bahl, dressed in character as JamStackMullet with a Mullet wig and sunglasses, watches the WP Engine Decode conference",
"caption": "Screenshot of the JamStackMullet watching WP Engine Decode conference"
}
}
}
Screenshot of a query for a post and some blocks using WPGraphQL for Gutenberg.

GraphQL Schema as the contract

Having the GraphQL Schema serve as the contract between the client and server allows each part of the application to move forward at its own pace. There’s now an agreement for how things will behave. If the contract is broken, for example, if the server changed the shape of one of the Types in the GraphQL Schema, it’s easily identifiable and can be fixed quickly, because the client specified exactly what was needed from the server by way of a GraphQL Query.

This removes the “just guess” pattern from decoupled application development with Gutenberg.

Teams that know nothing about WordPress can even make use of the data. For example, a data warehouse team, a native mobile team, a print team, etc. The GraphQL Schema and tooling such as GraphiQL frees up different teams to use the data in their applications how they want.

Client in control

With clients querying Gutenberg blocks as data, this gives clients full control over the presentation of the blocks. Whether the blocks are used in a React or Vue website, or used for a Native iOS app that doesn’t render HTML, or used to prepare a newspaper for print, the client gets to ask for the fields that it needs, and gets to decide what happens with the data. No unexpected changes from the server, the client is in control.

Tradeoffs: Scaling issues

While WPGraphQL for Gutenberg gets us much closer to being able to query Gutenberg blocks as data, it unfortunately has a dependency that makes it very difficult to scale, and it comes back, again, to the lack of a proper server side registry for blocks.

Since Gutenberg Blocks aren’t registered on the server, WPGraphQL for Gutenberg has a settings page where users must click a button to “Update the Block Registry”.

Screenshot of the WPGraphQL for Gutenberg settings page

Clicking this button opens up Gutenberg in a hidden iFrame, executes the JavaScript to instantiate Gutenberg, gets the Block Registry from Gutenberg initialized in JavaScript, sends the list of registered blocks to the server and stores the registry in the options table of the WordPress database. The registered blocks that are stored in the database are then used to map to the GraphQL Schema.

Peter Pristas deservers an award, because this approach is a very creative solution to the frustrating problem of Gutenberg not respecting the WordPress server.

Unfortunately this solution doesn’t scale well.

Since Gutenberg blocks are registered in JavaScript, this means that the JavaScript to register any given block might be enqueued from WordPress on only specific pages, specific post types, or other unique individualized criteria.

That means the JavaScript Block Registry for Page A and Page B might be different from each other, and maybe also different from the registry for Post Type C or Post Type D. So loading one page in an iframe to get the block registry might not get the full picture of what blocks are possible to interact with in a decoupled application.

In order for the block registry that is generated from the iframe to be accurate, every page of every post type that Gutenberg is enabled on in the site would need to be loaded by iframe to account for cases where blocks were registered to specific contexts. Yikes!

Tradoffs: Schema design issues

In addition to the scaling issues, there are some concerns with some of the Schema design choices, and I’ll even take the blame for some of this, as I had many conversations with Peter as he worked on the plugin, and he followed my lead with some of my also poor Schema design choices.

One issue is infinite nesting. Gutenberg blocks, as previously discussed, can sometimes have nested inner blocks. In WPGraphQL for Gutenberg, querying inner blocks requires explicit queries and without knowing what level of depth inner blocks might reach, it’s difficult to compose queries that properly return all inner blocks.

WPGraphQL used to expose hierarchical data in a similar way, but has since changed to expose hierarchical data, such as Nav Menu Items, in flat lists. This allows for nested data in any depth to be queried, and re-structured in a hierarchy on the client .

The unlimited depth issue is commonly reported for projects such as Gatsby Source WordPress .

When to use

If Gutenberg is a requirement for your headless project, this might be a good option, as it allows you to query Gutenberg blocks as structured data. You gain a lot of the predictability that you miss with the other options, and can benefit greatly from features of GraphQL such as Batch Queries , coupling Fragments with components , and more.

So while WPGraphQL for Gutenberg is probably the closest option available for being able to predictably query Gutenberg blocks as data in decoupled applications, there are some serious questions in regards to production readiness, especially on larger projects, and you should consider these issues before choosing it for your next project.

Tradeoffs in mind, agencies such as WebDevStudios are using this approach in production , even for large sites.

Progress for the server side block registry

In 2020, some progress was made in regards to a server side registry for Gutenberg blocks.

While the official Gutenberg documentation still shows developers how to create new blocks fully JavaScript with no server awareness, the core Gutenberg blocks have started transitioning to have some data registered on the server.

You can see here that (as of Gutenberg 5.6.2, released in February 2021) core Gutenberg blocks are now registered with JSON files that can be used by the PHP server as well as the JavaScript client.

These JSON files are now used to expose blocks to the WP REST API.

This is progress!

Inner blocks, inner peace?

Unfortunately it’s not all the progress needed to have meaningful impact for decoupled applications to use Gutenberg. There’s a lot of information that a decoupled application would need about blocks that is not described in the server registry. One example (of many) being inner blocks.

Gutenberg has a concept called “Inner Blocks”, which is blocks that can have other blocks nested within. For example, a “Column” block can have other blocks nested within each column, while other blocks such as an Image block cannot have nested inner blocks.

The bit of server side registry that is now available for core Gutenberg blocks doesn’t declare this information. If we take a look at the Column block’s block.json file, we can see there’s no mention of inner blocks being supported. Additionally, if. we look at the Image block’s block.json file, we don’t see any mention of inner blocks not being supported.

In order for a decoupled application, such as the official WordPress iOS app, to know what blocks can or cannot have inner blocks, this information needs to be exposed to an API that the decoupled application can read. Without the server knowing about this information, decoupled applications cannot know this information either.

So, while there’s been a bit of a migration for the core WordPress blocks to have some server (and REST API) awareness, there’s still a lot of missing information. Also the community of 3rd party block developers are still being directed to build blocks entirely in JavaScript, which means that all new blocks will have no server awareness until the server registry becomes more of a 1st-class citizen for Gutenberg.

What’s next?

The beginnings of a move toward a server-side registry gives hope, and gives a bit of a path toward blocks being properly introspect-able and useful by decoupled teams and applications.

Specification for Server Side Registering Blocks

I believe that the step forward for Gutenberg + decoupled applications, is to come up with a specification for how Gutenberg blocks can be registered on the server to work properly with server APIs.

Once a specification is discussed, vetted, tested and published, the WP REST API, WP CLI and WPGraphQL, and therefore decoupled applications such as the WordPress native mobile app, would all make use of the spec to be able to interact with Gutenberg blocks.

I don’t fully know what this spec needs to look like, but I believe it needs to exist in some form.

Projects such as Gutenberg Fields Middleware from rtCamp , ACF Blocks , and Genesis Custom Blocks all take a server-first approach to creating new Gutenberg blocks, and I think there’s a lot to learn from these projects.

The blocks from these tools are created in a way that the WordPress server knows what blocks exist, what attributes and fields the blocks have, and the server can then pass the description of the blocks to the Gutenberg JavaScript application, which then renders the blocks for users to interact with.

Since the server provides the Gutenberg JavaScript application with the information needed to render the blocks to a content producer, this means the server can also provide the information to other clients, such as the native mobile WordPress app, or teams building decoupled front-ends with Gatsby, Gridsome or NextJS.

The future of decoupled Gutenberg

I believe that with a proper specification for registering blocks on the server, Gutenberg can enable some incredibly powerful integrations across the web.

My thoughts are that we can arrive at a specification for registering blocks that can enable block developers to provide pleasant editing experiences, while providing decoupled application developers with the ability to Introspect the GraphQL API, predictably write GraphQL Queries (and Mutations) to interact with blocks, and get predictable, strongly typed results that can be used in decoupled applications.

In an effort to start discussing what the future of a Gutenberg Block Server Registry Specification like this might look like, I’ve opened the following Github issue: https://github.com/wp-graphql/wp-graphql/issues/1764

If this topic interests you, and you’d like to be involved in discussing what such a specification might look like, please contribute ideas to that issue. Additionally, you can Join the WPGraphQL community on Slack community, and visit the #gutenberg channel and discuss in there.

In this article I want to dive into the current state of Gutenberg and WPGraphQL.

Read More
Hide
8 months ago
Post

Demolish Core Web Vitals Requirements With Headless WordPress

Easiest Migration Ever!Easiest Migration Ever!

Need Help Choosing a Plan?

We offer solutions for businesses of all sizes. For questions about our plans and products, contact our team of experts. Get in touch

Resource Center

Ignite 2021: Demolish Core Web Vitals Requirements With Headless WordPress

Posted by Abe Selig

Last updated on October 27th, 2021

Performance is a critical component of the user experience and Google’s Core Web Vitals drives that home. The new metrics add a user-centric lens to performance, and they now have a direct impact on your site’s findability and position in search.

In this on-demand session, hear from Google Web Ecosystem Consultant Salvatore Denaro Sr. and WP Engine Senior Product Marketing Manager Hashim Warren as they dive into the details of Core Web Vitals, what these new metrics mean for your site(s), and how you can optimize your site to deliver fast and beautiful digital experiences that delight users and rank higher.

Video: Demolish Core Web Vitals With Headless WordPress

Google Web Ecosystem Consultant Salvatore Denaro Sr. and WP Engine Senior Product Marketing Manager Hashim Warren discuss :
  • The importance of Core Web Vitals and why page experience is a key area of focus
  • How Headless WordPress delivers fast, delightful user experiences that crush Core Web Vitals

“Some developers want even more control over their sites and front-end. They want to deliver more performant experiences to users and use the tools they want, even outside of WordPress. To do that, they’re using Headless WordPress.”

Hashim Warren, Senior Product Marketing Manage r, WP Engine

Learn from experts at Google and WP Engine about Core Web Vitals, Headless WordPress and building sites that delight users and rank higher.

Read More
Hide
8 months ago
Post

Expanding Google Summer of Code in 2022 | Google Open Source Blog

We are pleased to announce that in 2022 we’re broadening our scope of Google Summer of Code (GSoC) with exciting new updates to the program. For 17 years, GSoC has focused on bringing new open source contributors into OSS communities big and small. GSoC has brought over 18,000 university students from 112 countries together with over 17K mentors from 746 open source organizations. At its heart, GSoC is a mentorship program where people interested in learning more about open source are welcomed into our open source communities by excited mentors ready to help them learn and grow as developers. The goal is to have these new contributors stay involved in open source communities long after their Google Summer of Code program is over. Over the course of GSoC’s 17 years, open source has grown and evolved, and we’ve realized that the program needs to evolve as well. With that in mind, we have several major updates to the program coming in 2022, aimed at better meeting the needs of our open source communities and providing more flexibility to both projects and contributors so that people from all walks of life can find, join and contribute to great open source communities.

Expanding eligibility

Beginning in 2022, we are opening the program up to all newcomers of open source that are 18 years and older. The program will no longer be solely focused on university students or recent graduates. We realize there are many folks that could benefit from the GSoC program that are at various stages of their career, recent career changers, self-taught, those returning to the workforce, etc. so we wanted to allow these folks the opportunity to participate in GSoC. We expect many students to continue applying to the program (which we encourage!), yet we wanted to provide excited individuals who want to get into open source—but weren’t sure how to get started or whether open source communities would welcome their newbie contributions—with a place to start. Many people can benefit from mentorship programs like GSoC and we want to welcome more folks into open source.

Multiple Sizes of Projects

This year we introduced the concept of a medium sized project in response to the many distractions folks were dealing with during the pandemic. This adjustment was beneficial for many participants and organizations but we also heard feedback that the larger, more complex projects were a better fit for others. In the spirit of flexibility, we are going to support both medium sized projects (~175 hours) and large projects (~350 hours) in 2022. One of our goals is to find ways to get more people from different backgrounds into open source which means meeting people where they are at and understanding that not everyone can devote an entire summer to coding.

Increased Flexibility of Timing for Projects

For 2022, we are allowing for considerable flexibility in the timing for the program. You can spread the project out over a longer period of time and you can even switch to a longer timeframe mid-program if life happens. Rather than a mandatory 12-week program that runs from June – August with everyone required to finish their projects by the end of the 12th week, we are opening it up so mentors and their GSoC Contributors can decide together if they want to extend the deadline for the project up to 22 weeks.
Image with text reads 'Google Summer of Code'

Interested in Applying to GSoC?

We will announce the GSoC 2022 program timeline soon.

Open Source Organizations

Does your open source project want to learn more about how to apply to be a mentoring organization? This is a mentorship program focused on welcoming new contributors into your community and helping them learn best practices that will help them be long term OSS contributors. A key factor is having plenty of mentors excited about teaching newcomers about open source. Read the mentor guide , to learn more about what it means to be a mentor organization, how to prepare your community, creating appropriate project ideas (175 hour and 350 hour projects), and tips for preparing your application.

Want to be a GSoC Contributor?

Are you a potential GSoC Contributor interested in learning how to prepare for the 2022 GSoC program? It’s never too early to start thinking about your proposal or about what type of open source organization you may want to work with. Read through the student/contributor guide for important tips on preparing your proposal and what to consider if you wish to apply for the program in 2022. You can also get inspired by checking out the 199 organizations that participated in Google Summer of Code 2021, as well as the projects that students worked on. We encourage you to explore other resources and you can learn more on the program website . Please spread the word to your friends as we hope these updates to the program will help more excited folks apply to be GSoC Contributors and mentoring organizations in GSoC 2022!
By Stephanie Taylor, Program Manager, Google Open Source

Over the course of GSoC’s 17 years, open source has grown and evolved, and we’ve realized that the program needs to evolve as well. With that in mind,

Read More
Hide
8 months ago

If you use it right, the internet is the most powerful tool in human history. But most people aren't using it to its full potential. Luckily, there's now a Twitter thread with advanced tips for every internet tool - using this exact hook. Here's the 10 best of them:

8 months ago

Google Summer of Code will be opening up to all newcomers of open source that are 18 years and older, and will no longer be solely focused on university students or recent graduates. This is a welcomed change for self-taught developers like myself. https://t.co/73CtjgPuJr

8 months ago
Post

Video SEO: How to Rank YouTube Videos on Google

Joshua HardwickJoshua Hardwick Head of Content @ Ahrefs (or, in plain English, I'm the guy responsible for ensuring that every blog post we publish is EPIC).
  • Tweets 78
Data from Content Explorer

Shows how many different websites are linking to this piece of content. As a general rule, the more websites link to you, the higher you rank in Google.

Shows estimated monthly search traffic to this article according to Ahrefs data. The actual search traffic (as reported in Google Analytics) is usually 3-5 times bigger.

The number of times this article was shared on Twitter.

Looking to get more YouTube video views from Google?

Google has sent over 160,000 views to our YouTube videos in the last ~12 months.

google search traffic youtube 1google search traffic youtube 1

That’s more views than the countless video embeds on our blog have sent us, which currently gets over 250,000 organic visits per month.

In this post, you’ll learn how to rank your YouTube videos on Google in 5 easy steps.

We’ve also included a few bonus tips on how to use videos to get more website traffic.

But first, let’s make sure we’re on the same page…

What is video SEO?

Video SEO is the process of getting more video views from Google and utilizing videos to increase organic traffic to your website.

In this guide, we’ll focus mainly on the first part: getting more views from Google.

What we’re not going to talk about is ranking videos higher on YouTube. If that’s your goal, read our full guide to YouTube SEO .

How to rank YouTube videos on Google

  1. Create an “optimized” video
  2. Upload an enticing thumbnail
  3. Add timestamps

Let’s go through each of these in more detail.

Step 1. Find video topics with “traffic potential”

Not every video has the potential to attract views from Google.

For instance, here’s a video with over 2.2 million views on YouTube:

youtube video with views 1youtube video with views 1

Yet it doesn’t rank on Google for anything:

youtube video no views 1youtube video no views 1

The reason for this is simple:

For a video to attract views from Google, two things have to be true:

  1. People need to be searching on Google for that topic. If nobody is searching for it, then nobody will click on your video even if it ranks.
  2. The topic must have “video intent.” This means that most searchers would prefer to watch a video about the subject instead of reading about it.

Keyword research tools can help with finding topics that people are searching for. You can then look for videos in the search results to infer “video intent.”

video carousel 1video carousel 1

The logic here is that because Google aims to give users what they want, seeing videos in the search results is a clear sign that searchers want to watch a video.

The question is, how can you find these topics easily?

Simple. Look for relevant videos that get lots of traffic from Google, as these are clearly about topics with “video intent” that lots of people are searching for.

Here are three ways to do that:

1. Use Content Explorer

Content Explorer lets you search a database of over 1.1 billion web pages for mentions of a particular word or phrase. Within that index, there are currently over 47 million pages from YouTube.

To get started, run this search:

site:youtube.com inurl:watch title:topic

content explorer search 1content explorer search 1

Sort the results by search traffic from high to low. This should give you a list of relevant YouTube videos that currently get organic search traffic.

ce organic traffic 1ce organic traffic 1

For example, the macaroni and cheese video above gets an estimated 17,400 clicks from organic search every month.

If you had a cooking channel, it might be worth creating a video on this topic.

QUICK TIP

When looking for ideas in Content Explorer, it’s worth eyeballing the “Organic traffic” graph for the past six months to make sure that traffic is consistent over time.

ce organic traffic graph 1ce organic traffic graph 1

2. Use Site Explorer

Head to Site Explorer and search for youtube.com . Go to the “Organic keywords” report, then add a relevant keyword to the “Include” filter.

youtube site explorer 1youtube site explorer 1

Here, we see YouTube videos ranking for queries that include the word “recipe.”

If we click the caret next to any of these URLs, we see their estimated worldwide monthly organic traffic.

caret youtube url 1caret youtube url 1

For example, this video gets ~13,000 monthly organic visits. If we click on the video URL, we see that it’s a Belgian waffle recipe, so this is another topic that may be worth covering on a cooking channel.

QUICK TIP

Before pursuing a topic, hit the “Overview” link on the caret and check the “Organic traffic” graph to make sure that it’s consistent over time. You want to see a graph like this…

consistent organic traffic 1consistent organic traffic 1

… not like this:

declining topic 1declining topic 1

A big traffic spike followed by a small amount of traffic for a long period is a sign of a topic with waning interest.

3. Use Google and Ahrefs’ Batch Analysis tool

Add this free SERP scraper to your browser, then run this search on Google:

site:youtube.com [enter topic here]

Next, go to Settings > Search settings > then set the results per page to 100.

search settings 1search settings 1

Go back to the results and hit the SERP scraper to download the results.

Open the downloaded CSV, then copy-paste the YouTube URLs into Ahrefs’ Batch Analysis tool . Set the mode to “URL” and hit “Analyze.”

batch analysis url 1batch analysis url 1

Sort the results by the “Traffic” column to see which videos get the most organic search traffic.

batch analysis traffic 1batch analysis traffic 1

Consider making videos about these topics.

Step 2. Create an “optimized” video

Learning how to make YouTube videos that people love is beyond the scope of this guide.

But we are going to cover a few things to keep in mind during the creation process that may help you rank in Google SERP features like “key moments” and “suggested clips.”

how to rank youtube videos timestamps 1how to rank youtube videos timestamps 1

suggested clips google 1suggested clips google 1

Both of these have the potential to send more views to your videos .

For now, let’s focus our attention on “suggested clips.” (We’ll cover “key moments” in step #5) .

Judging by Google’s research paper , the way suggested clips are chosen from a technical standpoint isn’t that straightforward. So instead of focusing on the technicalities, let’s focus on actionable steps to take that may you help win them.

The first is to use simple language and “action verbs” to describe each step in the video. For example, if your video tells people how to cook rice, simple spoken instructions may be:

To begin, wash the rice with cold water. Repeat this process three times, then tip the rice into a pan. Add fresh water, bring to a boil, cover, then simmer for 15–20 minutes. Drain the excess water and serve .

Make sure to avoid unnecessary fluff and distractions between instructions where possible. In other words, don’t go off on a tangent explaining how your mom once deviated from one of the steps and ended up with burnt rice. This will only reduce clarity, which may confuse Google’s language processing algorithms.

The second is to ensure that your audio is clear and high quality. To do this, use a decent microphone and keep background noise to a minimum.

The third is to show what you’re talking about on the screen as you talk about it.

For instance, if you tell people to “put the pan on the hob,” show footage of that process on screen as you do so. This may increase Google’s confidence that the spoken instructions align with the content of the video.

Step 3. Fix your closed captions

YouTube automatically adds closed captions to videos. The problem is that these are rarely perfect. Misspelled words and grammatical errors are a common issue.

Just take a look at these auto-generated captions from one of our old YouTube videos:

youtube bad translation 1youtube bad translation 1

YouTube thinks Tim is saying “team solo from a traps” when he’s actually saying “Tim Soulo from Ahrefs.”

For that reason, it’s best to add your own.

Here’s what one of the videos on YouTube’s Creator Academy says about CC’s:

In terms of search, discovery, and engagement, captions are one of the most powerful pieces of data out there. The internet is text-based, so your video is going to stay hidden from search engines unless the text attached to it can be picked up. It can be hard to get across the essence of your video in just a title or description, even tags have a character limit. But a closed-caption file delivers a text-based transcript of your entire video and opens it up to search engines.

That same video goes on to say:

Text on screen has proven to be so engaging that it increases the watch to completion rate. These two factors lead to a monumental gain in SEO ranking and engagement.

Given these quotes, it seems that adding CC’s helps with two main things:

  1. Understanding your video . Google won’t rank your video without understanding what it’s about, and closed captions appear to help with that.
  2. Engagement . Lots of people watch videos in noisy or sound-sensitive environments, and over 5% of the world’s population has hearing loss of some degree. Closed captions help ensure that your video is useful to more people. That improves engagement, which, in turn, may lead to higher rankings in Google.

It’s also worth noting that if you’ve scripted your video, it doesn’t take long to fix closed captions manually, so it’s well worth doing.

Step 4. Upload an enticing thumbnail

Videos with poor thumbnails won’t get as many clicks from Google as those with enticing ones.

Here’s an example of a lousy thumbnail in a video carousel for the query, “how to make pancakes”:

unenticing video thumbnail 1unenticing video thumbnail 1

Not only is this visually dull and uninspiring, but the thumbnail shows an egg, not pancakes.

Here are a few tips for creating thumbnails that entice searchers to click:

Use a custom thumbnail

Don’t choose a still from your video. Create a custom and enticing thumbnail to grab the searcher’s attention.

Use the correct aspect ratio

Google shows video thumbnails in the 16:9 format. As a result, those with other aspect ratios can look odd in the search results, and that may dissuade the click. bad thumnail aspect ratio 1bad thumnail aspect ratio 1

Use a congruent image

Create a thumbnail that visually demonstrates that the video solves the user’s query.

For example, if someone searches for “how to tie a tie,” then this thumbnail makes sense because it shows someone tying a tie:

incongruent how to tie a tie thumbnail 1incongruent how to tie a tie thumbnail 1

On the other hand, this one doesn’t make much because you can barely tell that the kid is wearing one:

incongruent how to tie a tie 1incongruent how to tie a tie 1

Use contrast to your advantage

Avoid colors like white, grey, and red on your thumbnail as they blend in with search results. Instead, use contrasting colors that stand out.

We tend to use dark blue and orange.

keyword research video carousel 1keyword research video carousel 1

Use descriptive text on the thumbnail

This is something we do for all of our YouTube videos. For example, our video about learning SEO has the words “Learn SEO” on the thumbnail.

learn seo thumbnail 1learn seo thumbnail 1

Usually, we go for something short that complements the title of the video.

Whatever text you use, make sure that it’s written in an easy-to-read font, and looks good at both small and large sizes.

Step 5. Add timestamps

Earlier, we briefly mentioned the “key moments” that Google sometimes shows in search results.

how to make a podcast 1how to make a podcast 1

Here’s what Google says about these:

When you search for things like how-to videos that have multiple steps, or long videos like speeches or a documentary, Search will provide links to key moments within the video […] You’ll be able to easily scan to see whether a video has what you’re looking for, and find the relevant section of the content.

Google also says:

If your video is hosted on YouTube, Google Search may automatically enable clips for your video based on the video description on YouTube, and you may not have to mark specific timestamps in your YouTube description. However, you can tell us more explicitly about the important points in your video and we will prefer that information.

Long story short, Google is probably more likely to show “key moments” for your videos if you mark important points in the YouTube description.

To do that, use timestamps and labels.

  • What’s a timestamp? This is when a clip starts in the [hour]:[minute]:[second] format. You can negate the [hour] if it’s not needed. Video timestamps are automatically linked.
  • What is a label? This is a brief and clear description of the clip.

You can see an example of timestamps and labels on our video about YouTube SEO .

timestamps and labels youtube 1timestamps and labels youtube 1

These nine timestamps take viewers to sections of the video about what YouTube SEO is , YouTube keyword research , identifying search intent , and so forth.

Seemingly thanks to these optimizations, Google now shows “key moments” for our video for the query, “how to rank YouTube videos.”

how to rank youtube videos timestamps 1how to rank youtube videos timestamps 1

The same is true for our video about link building with Google sheets.

timestamp results link building google sheets 1timestamp results link building google sheets 1

Here are some tips for adding timestamps and labels :

  • Add timestamps to the video description. Don’t place it in a pinned comment.
  • Place each timestamp on a new line . Specify the label on the same line.
  • Keep the label brief but descriptive. Your label should be a direct statement of what the section is about (e.g., “Boil the pasta” not “Put your pasta in the pan and cook it for 10–15 minutes until al dente”)
  • List timestamps in chronological order . Don’t add a timestamp for something at the end of your video before earlier points.
  • Keep labels to around 40 characters or less. Google truncates longer ones.
  • Don’t add too many timestamps . Google hasn’t mentioned a maximum or a minimum number of timestamps they’ll show in search results. However, it’s unlikely that they’ll show a carousel with hundreds of them. As a general rule of thumb, we’d recommend no more than ten timestamps per video.
  • Align the on-screen content with the label. If your label says “Chop the onion,” try to add the timestamp when you’re visibly chopping the onion on the screen.

Note that “key moment” results are only available for YouTube videos at present, so this isn’t something that works for videos hosted elsewhere.

However, Google has said they’re planning to introduce support for other videos soon.

We’re also introducing a way for more content creators across the web to mark up their videos so they can be more easily searchable. Soon you’ll be able to find these key moments from video publishers around the world, such as CBS Sports and NDTV, as they add markup to their videos

Bonus tips: How to use videos to get more website traffic

Video SEO is not only about getting more YouTube video views from Google. It also involves utilizing videos to attract more traffic to your website from organic search.

Below are three tips to help with that.

1. Embed relevant videos on top-ranking pages

Google has a “Videos” tab, where there are two types of results:

  1. Relevant YouTube videos;
  2. Pages from the organic results with relevant video embeds

That second one is important. It means that if you’re ranking high in Google already, you can get those pages to show up in Google’s “Videos” tab by embedding a relevant video.

When someone clicks one of these results, Google sends them to your website—not YouTube.

videos tab website click 1videos tab website click 1

In fact, video embeds have sent over 25,000 visits to our blog from Google over the past three months:

video clicks search console 1video clicks search console 1

So how do you find the best pages to embed relevant videos?

Easy. Go to the “Search Results” report in Google Search Console , click the “pages” tab, then sort the results by clicks from high to low. This shows the pages that received the most traffic from Google over the past few months.

ahrefs clicks search console 1ahrefs clicks search console 1

Don’t use Search Console?

Paste your domain into Ahrefs’ Site Explorer and go to the “Top Pages” report to see those with the most estimated traffic.

top pages ahrefs 1top pages ahrefs 1

Look for pages where you have a relevant and useful video on a similar topic, then embed that video on the page when and where it makes sense.

For example, our guide to YouTube tags is one of our top posts with around 2,400 search visits per month. But unfortunately, it doesn’t appear in Google’s “videos” tab because we don’t yet have a video about YouTube tags to embed in the post.

However, we do have a related, helpful video about YouTube SEO, so we decided to embed that at the end of the post instead.

youtube tags embed 1youtube tags embed 1

Shortly after doing this, our page appeared in the videos tab for the query, “YouTube tags”:

youtube tags video tab 1youtube tags video tab 1

This has already sent a few clicks our way in just a few days.

youtube tags video traffic 1youtube tags video traffic 1

2. Add schema markup for embedded videos

Google sometimes shows video rich results for web pages with embedded videos.

video results self hosted 1video results self hosted 1

However, Google says that pages aren’t eligible for this type of result unless the embedded video is marked up using the correct schema code:

You must include the required VideoObject properties for your content to be eligible for display as a video rich result.

From our observations, this isn’t strictly true.

If your embedded video is hosted on YouTube, Google often shows a video rich result even in the absence of VideoObject schema markup.

For instance, here’s a video rich result for a Medium post with an embedded YouTube video:

video rich result 1video rich result 1

If we check that URL with Google’s Structured Data Testing tool , we see that there’s no VideoObject markup on the page.

no videoobject 1no videoobject 1

That said, Google still recommends adding video markup for embedded videos, even if they’re hosted on YouTube.

Sidenote. If you’re hosting videos on your own site, Google needs to see VideoObject markup before it considers them for video rich results.

If you use WordPress, adding this markup is straightforward with a free plugin like Schema & Structured Data for WP & AMP . Once installed, hit Structured Data > Schema types on the menu.

plugin menu 1plugin menu 1

Next, click the “Add Schema type” button.

add schema type button 1add schema type button 1

Select “VideoObject” from the dropdown, then hit “Next” again.

videoobject schema select 1videoobject schema select 1

Click the “Post type” dropdown and change it to “Show globally.”

show globally 1show globally 1

Hit “next” one final time, and you’re done.

Now, whenever you’re editing a post or page, there should be an option to “Modify current schema” at the bottom of the editor.

modify current schema 1modify current schema 1

Click this, and you’ll see options to toggle VideoObject markup on or off, and to add attributes.

schema data wordpress 1schema data wordpress 1

The attributes that Google says you must fill in are:

  • Name;
  • Description;
  • Upload Date;
  • Thumbnail Url

All other fields can be left blank, although we recommend filling in useful attributes like duration .

If you’re not using WordPress, watch this video and read the schema.org VideoObject documentation to learn how to add this manually.

To verify that the markup was added correctly, use Google’s Structured Data Testing tool .

3. Add transcriptions to “thin” pages with embeds

If you’re planning to embed a video on a web page with little or no text, consider publishing it alongside a written transcript.

This is what Moz does with their Whiteboard Friday videos, and some of them get lots of traffic from Google.

moz whiteboard friday video traffic 1moz whiteboard friday video traffic 1

Sidenote. Moz’s videos aren’t hosted on YouTube, but the point still stands.

From a UX standpoint, this is a positive move because some visitors prefer reading over watching a video—and Google wants to rank content that appeals to as many searchers as possible.

Just don’t paste and publish the transcript verbatim. Edit and format the copy as a blog post. Add subheadings and images to make the published transcript a good alternative for those who prefer text over video.

Final thoughts

Video SEO is a dynamic topic because Google is continually changing the way they display videos in the search results. That said, the two overarching “best practices” remain static:

  1. Create enticing and engaging videos for users;
  2. Do everything in your power to help Google better understand that content, to increase the chances of them showing your videos in web search results.

Did I miss anything important? Leave a comment or ping me on Twitter .

Follow these 5 easy steps to get more YouTube video views from Google.

Read More
Hide
8 months ago

FREE online digital courses: YouTube Creator Academy: https://t.co/Wy2M1RRQHB Google Digital Garage https://t.co/ajm4KRH2Yf Google Analytics Academy https://t.co/GaCCqZHG5s Twitter Flight School https://t.co/SPoSRsuNph Facebook Blueprint https://t.co/m0WiWzLNLA

FREE online digital courses:
YouTube Creator Academy:
Google Digital Garage
Google Analytics Academy

Read More
Hide
Saved to
Content Creation
8 months ago
8 months ago

Want to accelerate your career? Write better. THREAD: The principles of powerful business writing:

Sahil Bloom
8 months ago
8 months ago

Okay y'all, since a bunch of us have picked up Docs for Developers lately, who wants to join me, @AishaBlake, &amp; @coffeecraftcode for a #TechTwitterBookClub? Starting Nov 18, we'll have a weekly Twitter chat to discuss a chapter. Thursdays @ 6pm PT. Let's learn together! https://t.co/8gFL0H46bd

Starting Nov 18, we'll have a weekly Twitter chat to discuss a chapter. Thursdays @ 6pm PT. Let's learn together!

Read More
Hide
Saved to
Content Creation
8 months ago
8 months ago
Post

The Writing Well Handbook

Our goal

This handbook helps you write nonfiction books and blogs.

What is writing?

Writing is the pursuit of thinking clearly with the help of paper. Writing slows down your thinking so you can dance with your ideas.

If people cannot write well, they cannot think well. And if they cannot think well, others will do their thinking for them.
—George Orwell

Why write nonfiction?

1. Clarity

Great minds became brilliant through communication. Great ideas emerge while writing or speaking—not before. When you express ideas, your brain can't help but to draw connections between them and advance them.

Writing is a laxative for the mind.

2. Leverage

Keeping thoughts to yourself is a disservice to others. If you have something important to say and you say it well, you send strangers down paths badly needed.

As history has shown, a writer can change the world from their couch. Writing is the most radical thing you can do without spending a dollar.

3. Connection

The most efficient way to meet interesting people is to become someone they already want to meet.

One way to do that is by doing cool things, writing about them, then getting the word out. Or podcast. Or vlog.

Whenever you distribute content with an authentic voice, similarly-minded people want to meet the person behind that voice.

What you'll learn

Together, we'll deconstruct any topic you want to write about. You'll learn to write plus rewrite your thoughts so that they're interesting, substantitive, and resonant.

  • Page 1: Ideas — Identify what to write about
  • Page 2: First Drafts — Generate insights on your topic
  • Page 3: Rewriting — Rewrite for clarity, intrigue, and succinctness
  • Page 4: Style — Rewrite for style and flow
  • Page 5: Practicing — Work toward mastery

I’ll provide a cheatsheet on the last page of this handbook, but I recommend taking notes. Doing so forces you to slow down and draw connections between ideas. This helps you internalize them. Reading without note-taking is like exploring new territory without drawing a map.

Tip — See the bottom of your screen for quick navigation links.

Who should read this?

This handbook is for:

  1. Advanced nonfiction writers wanting to improve their craft: You’ll encounter unique insights to better understand how exceptional writing works.
  2. Aspiring writers who fear publishing online: This handbook should increase your confidence. We'll overcome key blockers together.

Over the next 30 minutes, you'll become a much more deliberate writer. There's a science to nonfiction writing that many haven't realized.

Who's Julian Shapiro?

I spend thousands of hours deconstructing topics that interest me. I compile my insights into handbooks (like this one). Over a million people read them annually.

Readers like my writing for its density of insights and efficiency.

I also write threads on Twitter , which are read by over a million people per month. They're consistently among the most viral long-form content on Twitter.

Before this, I wrote a column for the largest tech news site, TechCrunch. And I authored a boring programming book for Pearson Education.

You can learn more about me on my about page .

Learn how to write well. Topics include figuring out what to write about, how to write an introduction, the writing process, writing style, and copyediting.

Read More
Hide
Julian Shapiro
8 months ago
8 months ago

Ryan Holiday is one of the best-selling nonfiction authors of the past decade. To date, his books have sold more than 3,000,000 copies. Here's the crazy story of how a digital marketer niched down and created his own category around Stoicism: https://t.co/IocI9j3zUg

Saved to
Niche Ryan Holiday
8 months ago
8 months ago

I’ve decided it is not in my best interest to continue to ignore whatever is going on (crypto, NFT, web3). This doesn’t mean I’m becoming an advocate, but I intend to be informed. Please send me your RELIABLE resources* *grifters need not respond

web3

Read More
Hide
Saved to
Web3
8 months ago
8 months ago

3 books I recommend to all entrepreneurs: 1. Radical Candor by Kim Scott 2. Antifragile by Nassim Nicholas Taleb 3. Mindset New Psychology of Success by Carol Dweck What’s your top book recco?

Saved to
Reading list
8 months ago
8 months ago

We live in the age of binge-reading. People listen to podcasts, articles, and audiobooks at 3x speed. But this speed consumption strategy is based on a flawed model of learning. Turns out, there's a more effective way to learn. 🧵

Saved to
learning
8 months ago
8 months ago

Freelance Pricing 101 💰 Everyone struggles to price their freelance projects. Until today. This is how you can get paid what you’re worth. Thread 🧵👇

8 months ago

Every company on Earth is becoming a media company. So if you learn to: • Film • Code • Write • Speak • Design • Tell stories You become an immediate 10x asset for any company on Earth. Or, even better, you can become your own company.

7 months ago