Search engine optimization is easy to discuss and surprisingly easy to ship incorrectly. A page can have a title and still expose the wrong canonical URL. A multilingual site can translate its text and still omit reciprocal hreflang links. A JSON-LD block can look plausible while failing to parse.

This tutorial uses SEO: The Definitive Guide as a small, inspectable reference implementation. It is a public MIT-licensed static site with English, Brazilian Portuguese, and Spanish pages. Its repository contains the HTML, CSS, JavaScript, images, robots.txt, sitemap.xml, GitHub Pages workflow, and a validator that checks the relationships between those files.

The goal is not to promise rankings. The goal is to make a multilingual static site easier to inspect before publishing.

TL;DR

Clone the repository, serve the files locally, run its Node.js validator, and inspect the generated HTML. The validator checks required files, language attributes, canonical URLs, reciprocal hreflang links, JSON-LD, internal anchors, external-link safety, section parity, image dimensions, the sitemap, and robots.txt.

Prerequisites

You need:

  • Git
  • Node.js, for the repository validator
  • Python 3, or another static file server, for a local preview
  • A public GitHub repository if you want to deploy with GitHub Pages

The site itself has no package installation step and no build tool. The current repository README documents Python 3.11+ for the broader project context, but the quick local preview only needs a server capable of serving static files. The validator uses Node's built-in modules.

1. Start from a reproducible checkout

Clone the project and enter the checkout:

git clone https://github.com/paladini/seo-basics-guide-definitive-edition.git cd seo-basics-guide-definitive-edition 

The current default branch is main. There is no release tag in the repository at the time of writing, so this walkthrough targets the checked commit on main, not an invented version number. For a production change, record the commit you reviewed and re-run the checks after pulling new changes.

2. Preview the site locally

A static server matters because opening an HTML file directly does not reproduce normal HTTP behavior. Start Python's built-in server from the repository root:

python -m http.server 8000 

Open http://localhost:8000. The repository has an English page at /, a Portuguese page at /lang/pt-br/, and a Spanish page at /lang/es/. Check all three instead of assuming that a working English page proves the translations are wired correctly.

The project is intentionally simple: the browser loads static HTML, CSS, JavaScript, and image assets. There is no server-side rendering and no runtime database. That makes the published artifact easy to host, but it also means every language page must contain its own metadata and links.

3. Run the repository's validator

From the repository root, run:

node scripts/validate-site.mjs 

The expected result is similar to:

✓ Static validation passed. 3 languages, 24 sections each. 

The validator checks more than whether files exist. For each language page it verifies the declared lang, a canonical link, all four alternate-language links, required page text, the social image, JSON-LD, and resolvable internal anchors. It also checks that external links include target="_blank" and rel="noopener".

It compares section IDs across the three pages. That check is useful because a translator can accidentally remove a section or rename an anchor while leaving the page visually attractive. A language switcher is only useful when it points to pages with comparable structure.

The full validation also checks that social images are valid 1200 by 630 PNG files, that the sitemap includes the canonical and translated URLs, and that robots.txt contains a sitemap directive. Use the quick mode only when you intentionally want to skip the image and sitemap checks:

node scripts/validate-site.mjs --quick 

For a release check, use the full command.

4. Inspect the metadata that search engines receive

Open index.html and inspect the <head>. The reference page includes a viewport declaration, a unique title, a description, a canonical URL, Open Graph fields, a Twitter card, Dublin Core fields, and JSON-LD.

The canonical URL says which URL represents the English page. The alternate links connect the English, Portuguese, Spanish, and x-default variants:

<link rel="canonical" href="https://example.com/"> <link rel="alternate" hreflang="en" href="https://example.com/"> <link rel="alternate" hreflang="pt-BR" href="https://example.com/lang/pt-br/"> <link rel="alternate" hreflang="es" href="https://example.com/lang/es/"> <link rel="alternate" hreflang="x-default" href="https://example.com/"> 

Replace the URLs with your real public URLs. Do not copy the example literally. Each language page should link back to the other variants, and the URLs should be reachable over HTTPS.

The JSON-LD in the project uses an @graph containing an Article, BreadcrumbList, Organization, and FAQPage. This helps machines interpret the page, but it is not a guarantee of a rich result or higher ranking. Google decides whether a search feature appears and whether the page meets its requirements.

5. Deploy with GitHub Pages

The repository includes .github/workflows/deploy-pages.yml. Its workflow runs on pushes to main and uses the official GitHub Pages actions to check out the repository, configure Pages, upload the repository as an artifact, and deploy it.

Create your own public repository from the project or copy the files into an existing static-site repository. In the repository settings, configure Pages to use GitHub Actions as the source. Push a change to the configured branch, then inspect the workflow run and the deployed URL.

Do not treat a green deployment as a complete SEO check. After deployment, open the home page and one page from each language. Inspect the rendered source or use curl to verify that the canonical and alternate links contain the production hostname rather than localhost or a template URL.

6. Verify the published artifact

A compact verification loop can look like this:

curl -I https://YOUR-USER.github.io/YOUR-REPO/ curl -L https://YOUR-USER.github.io/YOUR-REPO/ | grep -E 'canonical|hreflang|application/ld\+json' 

Then check the translated paths and the sitemap:

curl -I https://YOUR-USER.github.io/YOUR-REPO/lang/pt-br/ curl -I https://YOUR-USER.github.io/YOUR-REPO/lang/es/ curl -I https://YOUR-USER.github.io/YOUR-REPO/sitemap.xml curl -I https://YOUR-USER.github.io/YOUR-REPO/robots.txt 

This verifies transport and obvious metadata presence. It does not replace a browser check, the repository validator, Google Search Console, or a structured-data test. A successful HTTP response only proves that a server returned bytes.

Why this workflow works

The repository puts the validation rules beside the content. That makes the SEO contract reviewable in a pull request instead of leaving it as a manual checklist in someone's memory.

It also keeps the runtime small. GitHub Pages only needs the generated static files, while the workflow publishes the same tree that was reviewed. The tradeoff is that content authors must update repeated metadata deliberately across languages. The validator catches structural drift, but it cannot judge whether a translation is natural, whether a title matches search intent, or whether a page is genuinely useful.

Failure modes and security boundaries

Common failures include a missing content path in a different static-site project, a canonical URL copied from the example, a one-way hreflang link, a sitemap that lists URLs which return errors, and a JSON-LD block with invalid JSON. Test the actual deployed hostname after every domain or repository rename.

The project is static and MIT-licensed, but that does not make every linked third-party tool safe or authoritative. Review external scripts, images, and links before adding them. The reference pages use external font and content links, so a privacy-sensitive deployment should decide whether to self-host those assets.

SEO is not a security boundary. Do not put secrets, private documents, analytics credentials, or unpublished customer data in a public repository or a static artifact. GitHub Pages is suitable for content intended to be public, not for an authenticated application.

FAQ

Does this guarantee better rankings?

No. It reduces common technical and metadata mistakes. Search visibility also depends on content quality, relevance, competition, links, crawling, indexing, and many factors outside this repository.

Do I need a framework?

No. Plain static HTML is enough for canonical links, hreflang, JSON-LD, a sitemap, and robots.txt. A framework can help at larger scale, but it does not remove the need to validate the output.

Is meta keywords required?

No. The project's own FAQ correctly advises focusing on titles, helpful content, internal linking, and structured data instead of the obsolete meta keywords tag.

What should I test first?

Run the full repository validator, then test the production URL and all language paths. Fix canonical, alternate-link, sitemap, and broken-asset problems before measuring search performance.

Takeaway

A multilingual SEO site is a set of relationships: each page needs consistent metadata, each language needs reciprocal links, and the sitemap must describe reachable URLs. A plain static repository plus a focused validator makes those relationships visible and repeatable.

If you maintain a multilingual static site, which check has caught the most expensive mistake for you: canonical URLs, hreflang, structured data, or the sitemap?

AI assistance disclosure

AI assistance was used to organize this tutorial and improve its wording. The repository metadata, README, validator implementation, GitHub Pages workflow, MIT license, current default branch, local validation result, and public site response were checked before publication. The SEO guidance is linked to primary documentation where applicable; no ranking or traffic outcome is promised.