Provide documentation on configuring .jsonld files to be loaded as script #9052

thadguidry · 2023-06-09T03:09:19Z

Have you read the Contributing Guidelines on issues?

I have read the Contributing Guidelines on issues.

Description

We currently do OK by mentioning that scripts can be loaded.
https://docusaurus.io/docs/api/docusaurus-config#scripts
Great!

However, we should provide an example to also be linkable to our SEO section for https://docusaurus.io/docs/seo#structured-content.

For example, it's unclear what or where the best convention is (so we should provide a paragraph on guidelines under structured-content and also under the API reference for docusaurus-config#scripts) when a user has created their .jsonld file for Schema.org context to be loaded. Where to place the .jsonld file in Docusaurus file hierarchy is a bit unclear as a best practice. Should it go under /src? Or /static? or /assets? somewhere else?

where in Docusaurus file heirarchy do I place my seo_homepage.jsonld file to be properly loaded in this example?

module.exports = {
  scripts: [
  { src: 'https://plausible.io/js/script.js',
    'data-domain': 'homihq.com',
    defer: true,
    async: false,
  },
  { src: 'seo_homepage.jsonld',
    type: 'application/ld+json',
    defer: true,
    async: true,
  },
  ],

Self-service

I'd be willing to address this documentation request myself.

The text was updated successfully, but these errors were encountered:

slorber · 2023-06-09T12:30:49Z

How is this specific to Docusaurus?

Where to place the .jsonld file in Docusaurus file hierarchy is a bit unclear as a best practice. Should it go under /src? Or /static? or /assets? somewhere else?

/src: if you don't require that script, it won't be in your production build and will only be ignored. What exactly gives you the idea to do this?
/static: yes, as documented anything you put there will be in your prod deployment
/assets: what is this folder? If you refer to build/assets it's a generated folder and is not even supposed to be on your Git 🤷‍♂️

where in Docusaurus file heirarchy do I place my seo_homepage.jsonld file to be properly loaded in this example?

How would you do this on any other non-Docusaurus site?
What prevents you from doing the exact same in Docusaurus?
How this file is different from any other script like the plausible analytics one?

The general guideline is that anything in /static is in your production deployment, so you can just link to it with a path, there's no magic here.

Docusaurus can't be a reference regarding SEO and structured data, there are other reference sites that explain good practices.

I'm not an expert but as far as I know, you can insert structured data:

as an external resource script (like you suggest here)
as an inlined script tag (you can do that using the <Head> API, example)
as JSX props microdata (example)

None of those methods are specific to Docusaurus. We provide generic apis that allow you to do that, but can't document all the use-cases for using those apis.

Note that the 2/3 methods allow you to provide structured data that is different for each page of your site, while the 1st is more for site-wide structured data.

slorber · 2023-06-09T12:35:41Z

cc @johnnyreilly maybe you have an opinion on how we could lightly document how to use microdata/jsonld/structured data?

We probably don't want to copy/paste authority sites best practices but we could add some external links and mention various possibilities.

thadguidry · 2023-06-09T12:52:30Z

I've tried many different things to get my local .jsonld file content to be added either into the <script> tag which does get created successfully.
Here's the tag snippet that does indeed get created:

<script src="seo_homepage.jsonld" type="application/ld+json" defer="" async=""></script>

I didn't see the jsonld file being copied into sources anywhere in the left panel?
LINE 14:

But more importantly, notice the content of the jsonld file itself does not show up in between the <script> tags?

FILE: seo_homepage.jsonld

{
    "@context": "https://schema.org",
    "@type": "Organization",
        "name": "Homi",
        "url": "https://homihq.com",
        "logo": "https://homihq.com/img/logo-black.png"
}

Maybe the issue is how I'm trying to read from src: ? or the pathing as in my original comment above? or maybe I need to resolve() specially? So I thought that we could slightly improve the docs, as well as figure out why something that did seem documented well enough and simple, doesn't seem to be working as I expected.

thadguidry · 2023-06-09T12:55:00Z

I'm happy to push this over to the docusaurus.community site, but I thought a brief mention of jsonld handling could benefit everyone with a small paragraph explaining how you might accomplish something like what I am trying to do.

slorber · 2023-06-09T13:19:29Z

I didn't see the jsonld file being copied into sources anywhere in the left panel?

Adding scripts to config does not magically make those scripts part of your deployment.

Any /static file is supposed to be copied to /build and become part of your Docusaurus deployment. If that's not the case you can open an issue with a repro.

But more importantly, notice the content of the jsonld file itself does not show up in between the <script> tags?

I don't understand what you mean by "the content of the jsonld file itself does not show up in between the <script> tags"

Docusaurus does no magic here, if you add a script tag, it will add the script page to the html page as is, that's all it does. Don't expect Docusaurus to fetch the content of it and insert it as a string in the static page.

Having the script tag added this way to your page is definitively the expected behavior:

<script src="seo_homepage.jsonld" type="application/ld+json" defer="" async=""></script>

Maybe the issue is how I'm trying to read from src: ? or the pathing as in my original comment above? or maybe I need to resolve() specially?

I have no idea what you mean by "trying to read from src". scripts are added as is, unmodified. It is your responsibility to make sure the URL or relative/absolute path you reference in the script exists, and there's not a single way to do that.

So I thought that we could slightly improve the docs, as well as figure out why something that did seem documented well enough and simple, doesn't seem to be working as I expected.

My intuition is that you try to put src/seo_homepage.jsonld and then use a script with src seo_homepage.jsonld. Where do you see it documented anywhere that it's something you should do?

Eventually you should do static/seo_homepage.jsonld and use a script with /seo_homepage.jsonld

Again, Docusaurus does absolutely 0 magic here, it just adds a script tag as is. There's no "processing" or whatever, it is just how html works.

If all your pages contain a script with src seo_homepage.jsonld (no leading slash), then your browser will consider it as a relative pathname and resolve against the current page, which is likely not what you want. For example it will try to load /docs/myCategory/seo_homepage.jsonld while you are on page /docs/myCategory/myDoc, because that's how the web simply works.

thadguidry · 2023-06-10T00:17:26Z

@slorber Firstly, thanks for your patience! Still having bits of problems, but anyways I was frantically trying to find the easiest route to add this to only the homepage:

<script src="seo_homepage.jsonld" type="application/ld+json" defer="" async="">
{
    "@context": "https://schema.org",
    "@type": "Organization",
        "name": "Homi",
        "url": "https://homihq.com",
        "logo": "https://homihq.com/img/logo-black.png"
}
</script>

But I think I have my answer after spending a few hours all over the docs... which is unfortunate and where I think that structured-content section could improve.

After those few hours spent by me, I think what is likely the missing piece of documentation under the https://docusaurus.io/docs/seo#structured-content would be a light mention something along the lines of:

Sometimes you want to apply SEO changes only to the homepage or landing page. You can add additional custom <script>, <meta>, <link>, etc. tags to only the homepage by modifying /src/pages/index.js and using the <Head> API https://docusaurus.io/docs/docusaurus-core#head as its examples show.

What do you think of the above quote or similar going into that structured-content section in a PR by me?

thadguidry · 2023-06-10T02:25:06Z

THIS finally:

import Head from '@docusaurus/Head';
import MySEO from '@site/static/seo_homepage.json';

function CustomSEO() {
  return (
    <Head>
      <script src="" type="application/ld+json" defer="" async="">
        {JSON.stringify(MySEO)}
      </script>
    </Head>
  );
}

export default function Home() {
  const {siteConfig} = useDocusaurusContext();
  return (
    <Layout
      title={`${siteConfig.title}`}
      description="Low code API Development. <head />">

//  ---- USE IT HERE ?
        <CustomSEO />
// ----
      <HomepageHeader />
      <main>
        <HomepageFeatures />
      </main>
    </Layout>
  );
}

The script jsonld content finally gets added inside my <script> tag as seen below. Great! But then I get what seems to be many duplicated elements for <link rel="prefetch" inside <head> in the HTML as shown below screenshot?
So did I overload something where I should not have or is this some other problem?

slorber · 2023-06-14T16:04:59Z

Structured data is not different from any other head metadata, which is already covered on that page:
https://docusaurus.io/docs/seo#single-page-metadata

What makes you think that those 2 need a distinct treatment?:

<meta property="og:image" content="image.png" />
<script src="" type="application/ld+json" defer="" async="">

It's exactly the same case. There's an infinite of possible metadata we could add on this doc page, so do we really need to be exhaustive and try to document them all?

BTW, what is even the purpose of having src="" defer="" async=""? 🤷‍♂️

Eventually, we could make the <Head> example on that page show multiple distinct metadata like this:

export default function page() {
  return (
    <Layout title="Page" description="A React page demo">
      <Head>
        <meta property="og:image" content="image.png" />
        <meta name="twitter:card" content="summary_large_image" />
        <link rel="preconnect" href="https://example.com" />
        <script type="application/ld+json">
          {JSON.stringify({
            "@context": "https://schema.org/",
            "@type": "Organization",
            name: "Meta Open Source",
            url: "https://opensource.fb.com/",
            logo: "https://opensource.fb.com/img/logos/Meta-Open-Source.svg"
          })}
        </script>
      </Head>
      {/* ... */}
    </Layout>
  );
}

About the prefetch thing, that seems unrelated to me. If you see a bug related to this, open a repro. It might simply be due to localhost hot code reloading after your live edits.

thadguidry · 2023-06-14T22:52:30Z

You might be well right. So let's close this issue.

slorber · 2023-06-15T08:46:38Z

Great

Will still add a few other metadata in the example, this might help users to understand

slorber · 2023-06-15T09:17:10Z

Please review this PR and let me know if it makes things clearer: #9071

thadguidry added documentation The issue is related to the documentation of Docusaurus status: needs triage This issue has not been triaged by maintainers labels Jun 9, 2023

slorber removed the status: needs triage This issue has not been triaged by maintainers label Jun 9, 2023

thadguidry closed this as not planned Won't fix, can't repro, duplicate, stale Jun 14, 2023

slorber mentioned this issue Jun 15, 2023

feat(pages): add support for missing SEO front matter + improve SEO docs #9071

Merged

slorber closed this as completed in #9071 Jun 15, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Provide documentation on configuring .jsonld files to be loaded as script #9052

Provide documentation on configuring .jsonld files to be loaded as script #9052

thadguidry commented Jun 9, 2023 •

edited

Loading

slorber commented Jun 9, 2023 •

edited

Loading

slorber commented Jun 9, 2023

thadguidry commented Jun 9, 2023 •

edited

Loading

thadguidry commented Jun 9, 2023

slorber commented Jun 9, 2023

thadguidry commented Jun 10, 2023 •

edited

Loading

thadguidry commented Jun 10, 2023 •

edited

Loading

slorber commented Jun 14, 2023 •

edited

Loading

thadguidry commented Jun 14, 2023

slorber commented Jun 15, 2023

slorber commented Jun 15, 2023

Provide documentation on configuring .jsonld files to be loaded as script #9052

Provide documentation on configuring .jsonld files to be loaded as script #9052

Comments

thadguidry commented Jun 9, 2023 • edited Loading

Have you read the Contributing Guidelines on issues?

Description

Self-service

slorber commented Jun 9, 2023 • edited Loading

slorber commented Jun 9, 2023

thadguidry commented Jun 9, 2023 • edited Loading

thadguidry commented Jun 9, 2023

slorber commented Jun 9, 2023

thadguidry commented Jun 10, 2023 • edited Loading

thadguidry commented Jun 10, 2023 • edited Loading

slorber commented Jun 14, 2023 • edited Loading

thadguidry commented Jun 14, 2023

slorber commented Jun 15, 2023

slorber commented Jun 15, 2023

thadguidry commented Jun 9, 2023 •

edited

Loading

slorber commented Jun 9, 2023 •

edited

Loading

thadguidry commented Jun 9, 2023 •

edited

Loading

thadguidry commented Jun 10, 2023 •

edited

Loading

thadguidry commented Jun 10, 2023 •

edited

Loading

slorber commented Jun 14, 2023 •

edited

Loading