Mini lesson · English

How to add search to your website

Add a new supplied article with an assistant and verify that visitors can find and open it through the ready search page.

Start the interactive lessonRead the lesson below

Who is this for?

People who want readers to find topics on a small website. The search project is supplied; a coding assistant can maintain its technical index.

Before you start

The supplied blog/search workshop and a coding assistant to start the public folder over HTTP. You can use its ready articles; an existing personal blog is not required.

Estimated time: 14–26 min

Estimates for the supplied starter files with prerequisite accounts and tools ready. Setup, deployment queues and delivery/DNS waits take additional time. This simple public index suits small content sets. Large archives and multilingual ranking need a different search strategy.

What you will learn

  • Search the supplied content and open a real result.
  • Add a new article and keep search in step with it.
  • Distinguish no matches from unavailable search.

Workshop files

Step 1

Try the ready search

Find a topic and open the actual article.

Have the assistant start the supplied public folder over HTTP. Search a topic from one of the ready posts, then open a result and compare it with the promised title/summary.

Only public content should appear in search. Hiding a draft’s menu link does not make its included text private.

A concrete example

A search result is useful when it leads to the substantive article, not an empty page.

Use the supplied blog/search project. Add the supplied fourth article or my draft and update its search data together, keeping drafts private and destinations safe. Handle the index code for me. Help test a distinctive phrase, an absent topic and a failed search-data load, while preserving a way to browse articles.

Files for this step

Start hereWorkshop files

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Help visitors find the right article

Search should connect a question to a real page, not merely animate a search box.

The workshop extends the blog site with search.html, a JSON index and a browser script. It searches article titles and text and returns links to the existing pages.

The entire index is public and downloaded to the browser. Do not put private drafts or confidential notes into it. Search is a navigation feature here, not a permission system.

Worked example

Searching “image” returns the article about smaller image sources. Searching an unrelated word returns a clear no-results message while keeping the browse link available.

Extra implementation exercise

Can a draft stay private if you hide its page link but include its full text in search-index.json?

Show a worked solution

No. Anyone can download the JSON. Exclude private content from public search and enforce access on any genuinely private backend.

  • Recognizes the index itself is public.
  • Keeps private material out of public assets.

Step 2

Use a distinctive phrase

Choose something you can recognize in the article and search.

Pick a short distinctive topic phrase for the fourth supplied or new article. Ask the assistant to publish the article and update search data together.

Search does not automatically know a page exists just because it was saved. A simple word-based search can also miss typos or unfamiliar wording.

A concrete example

An exact phrase can isolate whether the new article was connected to search at all.

Files for this step

Start hereWorkshop files

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Match words and render safe results

Make the matching rule simple enough to explain and test.

The script lowercases the query, splits it into words and requires every word to occur somewhere in the article title/text. It is substring matching, not semantic search or typo correction.

It creates links with DOM methods and textContent. The index validator limits destinations to the expected blog filename format. That is useful even for a locally maintained index because it prevents accidental malformed or unsafe destinations.

The matching rule is AND across the query words, anywhere in the combined title and body. Word order does not matter: 'image browser' and 'browser image' have the same matches. It is not exact-phrase search. A word found only in the article body still counts; a misspelling does not receive automatic correction.

Worked example

“image browser” matches a page containing both words. “imagge” does not automatically become “image”. If you want typo handling later, add explicit behaviour and tests.

const matches = entries.filter(entry =>
  words.every(word => (entry.title + ' ' + entry.text)
    .toLowerCase().includes(word))
);

Extra implementation exercise

Why might a relevant article fail a query that contains a misspelled word?

Show a worked solution

The literal substring does not occur in its text. The current search has no typo correction; either correct the query or implement a tested alternative.

  • Describes the implemented literal matching.
  • Does not claim a failed request or semantic understanding.

Step 3

Check no-match and broken-search cases

Different states need different next actions.

Search an absent topic and inspect its no-match state. For an unavailable-data check, use a fresh page load and ask the assistant to block or fail the search-data request locally before the first search. The app reuses data after it loads, so blocking a later request alone may not reproduce the intended failure.

No matching article and search temporarily failing should have different messages. Keep the query available to correct or retry, and try the fallback route to browse all articles. Label a deliberately blocked request as a simulation, not a real outage.

A concrete example

A request error does not prove that no relevant article exists.

Files for this step

Start hereWorkshop files

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Separate no results from unavailable search

A failed index download does not prove that no article matches.

Run the supplied successful, missing-topic and blank-query cases. Then use developer tools to block search-index.json and reload before searching; the script caches a successfully loaded index in memory.

The failure message offers the article index. The visitor can still browse when search fails. Verify each result URL and test the form with the keyboard.

Worked example

“No matching articles” means a usable index was searched. “Search unavailable” means the index could not be obtained or validated. Those messages describe different evidence.

Extra implementation exercise

The JSON request returns 500. Should the page say there are no matching articles?

Show a worked solution

No. Report search as unavailable and retain the browse link. Only claim zero matches after successfully loading and checking the index.

  • Distinguishes transport failure from empty matches.
  • Offers a working alternative navigation route.

Step 4

Keep a new article searchable

Repeat the reader task after the change.

Complete the fourth article and matching search entry with your assistant. Reload so the running page uses current data, search the distinctive phrase and open the returned article.

Verify the loaded result reaches the actual new content. Keep no-match, failure and browse-all behavior working too.

A concrete example

The supplied turquoise-anchor example is a comparison, not a required personal writing topic.

Files for this step

Start hereWorkshop files

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Your assignment: keep search in sync with a new article

Publishing a page and making it searchable are separate steps in this small site.

Add a fourth article and a corresponding index entry. Choose a distinctive topic phrase and confirm it finds the new page. Keep the destination within the allowed blog filename pattern.

Remove that entry temporarily and observe that the page still exists but no longer appears in search. This exposes why a larger site may generate its index automatically from the article source.

Your fourth article can use any genuine topic and distinctive phrase. contact-anchor-check.html and “turquoise anchor check” are only the supplied comparison case, not required submission content. What matters is that your own real filename and searchable text agree in the article and loaded index.

Worked example

A static generator can produce pages and the index from one source. In this hand-maintained version, the test record is your protection against forgetting one side.

The complete reference walkthrough is available in reference/assignment-walkthrough.txt. Compare its steps with your own result; fill the test record from observations in your own project.

Extra implementation exercise

Publish the fourth sample article and prove search finds its distinctive phrase.

Show a worked solution

The reference fourth article uses the distinctive phrase 'turquoise anchor check'. The corresponding search-index.json entry has its real blog filename plus searchable summary/body text; the complete reference files show both sides.

Reload to clear the in-memory cached index, search that phrase and open the returned article. Inspect the loaded JSON too: merely placing the phrase in the HTML without updating the index will not make it searchable.

Retest a missing topic and a blocked index download in a fresh tab/reload. Missing matches and unavailable search must produce different messages, while Browse all articles still works.

  • Result opens the intended real article.
  • New content is indexed without breaking failure and empty-query handling.

Was this lesson useful?

Leave a like, or share it with someone who could use it.

Continue learning

Explore the other lessons