search

fsprojects / FSharp.Formatting

F# tools for generating documentation (Markdown processor and F# code formatter)
https://fsprojects.github.io/FSharp.Formatting/
Other
464 stars 155 forks source link

SEO-optimization for new theme #869

Closed Thorium closed 10 months ago

Thorium commented 10 months ago

The current documentation pages should win Google search by default, but GitHub and Nuget seems to go before that. So... The HTML pages could have better parameters in the head of the page, for example:

<head>
<!-- ... current ones plus ... -->
<meta name="description" content="Library used for building custom analyzers for FSAC / F# editors.">
<!-- OGs are for social media sharing previews -->
<meta property="og:site_name" content="FSharp.Analyzers.SDK">
<meta property="og:image" content="http://ionide.io/FSharp.Analyzers.SDK/images/logo.png">
<meta property="og:image:secure_url" content="https://ionide.io/FSharp.Analyzers.SDK/images/logo.png">
<!-- match Twitter option with Some 
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@fsharp_analysers">
<meta name="twitter:image" content="http://ionide.io/FSharp.Analyzers.SDK/images/logo.png">
-->
<!-- This would be for your mother's phone: -->
<!--link rel="apple-touch-icon-precomposed" sizes="144x144" href="http://ionide.com/apple-touch-icon-144-precomposed.png"-->
</head>
kMutagene commented 10 months ago

If i understand the current system correctly, there is no default _template.html file provided by the tool, and users are expected to create their own. I think a fsdocs init command that provides a html template that contains the seo tags would be nice, but to make this automated, a lot of parameters have to be supplied by the user.

Example:

This is how i try to do automatic seo tags for each documentation page on plotly.net:

    <meta charset="utf-8">
    <title>{{fsdocs-page-title}}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <meta name="author" content="{{fsdocs-authors}}">
    <meta name="description" content="Plotly.NET is an Interactive charting library for .NET programming languages. This page contains the documentation for: {{fsdocs-page-title}}">

    <!-- Opengraph properties (https://ogp.me/) -->
    <meta property="og:title" content="Plotly.NET documentation for: {{fsdocs-page-title}}" />
    <meta property="og:url" content="{{root}}{{fsdocs-source-basename}}.html">
    <meta property="og:type" content="website" />
    <meta property="og:site_name" content="Plotly.NET" />
    <meta property="og:description" content="Plotly.NET is an Interactive charting library for .NET programming languages. This page contains the documentation for: {{fsdocs-page-title}}">
    <meta property="og:image" content="{{root}}img/logo_meta_tags.png">

    <!-- Twitter cards -->
    <meta name="twitter:card" content="summary_large_image">
    <meta property="twitter:domain" content="{{root}}{{fsdocs-source-basename}}.html">
    <meta property="twitter:url" content="https://plotly.net">
    <meta name="twitter:title" content="Plotly.NET documentation for: {{fsdocs-page-title}}">
    <meta name="twitter:description" content="Plotly.NET is an Interactive charting library for .NET programming languages. This page contains the documentation for: {{fsdocs-page-title}}">
    <meta name="twitter:image" content="{{root}}img/logo_meta_tags.png">

As you see, this is done via the substitution parameters, but if the user does not supply these, the meta tags are rubbish.

nojaf commented 10 months ago

If i understand the current system correctly, there is no default _template.html file provided by the tool, and users are expected to create their own.

That is incorrect if you don't create a _template.html file, https://github.com/fsprojects/FSharp.Formatting/blob/main/docs/_template.html will be used by the tool.

We could incorporate these SEO tags in the default template and add some more substitution parameters if necessary.

As for fsdocs init I do like that idea. It could scaffold the right files if you have absolutely nothing in your repository.

kMutagene commented 10 months ago

That is incorrect if you don't create a _template.html file

I see, sorry has been a long time since i did set up from scratch

We could incorporate these SEO tags in the default template and add some more substitution parameters if necessary.

These are always known to the tool right?

If that is the case, most of the tags can be reliably created, while i think {{fsdocs-authors}} must be provided by the user, and therefore could just be left out of the template, preventing people from ending up with '{{fsdocs-authors}}' as their author tag.

nojaf commented 10 months ago

Available in https://www.nuget.org/packages/fsdocs-tool/20.0.0-alpha-015