
# Documents

A document is what a search finds: a page, a section of one, a product, a note. It has an `id`, searched `fields`, a `language`, a `link` and `attributes` shown with it. Documents come from Markdown files (`spring.search.markdown`) and from any bean that implements `SearchDocumentSource`.

## Why

The search does not own your data: it reads it from where it already is. Markdown files of `lib/resources/` need only a property; a repository or an API needs a small bean. The index is built from them at the first search, one per language.

## SearchDocument

```dart
SearchDocument(
  id: 'book-42',
  fields: {'title': book.title, 'body': book.summary},
  link: '/books/42',
  language: 'en',
  attributes: {'price': '12.90'},
)
```

| Field | Meaning |
|---|---|
| `id` | Unique among the documents of its language |
| `fields` | The searched texts by field name: `title`, `heading`, `body`, or your own, weighted by `spring.search.fields` |
| `language` | The language of the texts (`en`, `ja`); `null` for `spring.search.default-language` |
| `link` | Where the document is shown: a route, a URL; `null` when the app finds it by `id` |
| `attributes` | What the app shows with a hit (a section's name, a price); not searched |

`document.title` is the `title` field, empty when there is none.

## Markdown files

```yaml
spring:
  search:
    markdown:
      - location: resources:content/docs/**/*.md
        exclude: ['**/contents*.md', '**/_*.md']
        link: /docs/{path}
      - location: resources:content/blog/*.md
        link: /blog/{path}
```

Each entry cuts the files of its location into one document per section: the opening text, then one per heading of level two and below (`##`, `###`, ...):

| Field or attribute | Value |
|---|---|
| `title` (field) | The page's title: the front matter's `title`, else its first `#` heading |
| `heading` (field) | The section's heading; empty for the opening text |
| `body` (field) | The section's text, without the Markdown's marks; code stays as written |
| `link` | The page's link, then the section's GitHub anchor: `/docs/core/beans#bean-factory` (the opening text has none) |
| `page` (attribute) | The page's link, for `spring.search.collapse-by: page` |
| `section` (attribute) | The heading |
| `path` (attribute) | The file below `lib/resources/` |

- `{path}` in `link` is the file's path from the location's directory, without `.md`, its language and a last `index`: `content/docs/core/beans.md` is `/docs/core/beans`, `content/docs/guides/index.md` is `/docs/guides`.
- `name.ja.md` is the Japanese of `name.md`, at the same link. A page without a translation is also searched in the other languages, in its own.
- `exclude` patterns are relative to the location's directory.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.search.markdown[n].location` | `resources:` or `asset:` pattern | required | The files (`resources:content/**/*.md`, `asset:docs/**/*.md`) |
| `spring.search.markdown[n].exclude` | list of patterns | none | Files left out, relative to the location's directory |
| `spring.search.markdown[n].link` | text with `{path}` | `/{path}` | The link of a page |

A location of `resources:` or `asset:` works the same: `{path}`, `exclude` and the `path` attribute are relative to the location's folder. Files left out of the binary (`spring.resources.embed.exclude`) are found as well.

`MarkdownSearchSource` reads one language at a time. Its `languages` come from the file names, and `documentsIn(language)` reads only the files of that language, plus the default-language file of a page without a translation. A site whose pages are downloaded on the web (files left out of the binary) fetches only the pages of the language searched. With the index the build writes (`spring.search.prebuilt`, the default) it fetches none: the search reads one file per language ([The index the build writes](searching.md#the-index-the-build-writes)).

For another link or other fields, make a `MarkdownSearchSource` bean of your own.

## A source of your own

Any bean that implements `SearchDocumentSource` gives documents. It is read when the index is built, and again when it is invalidated:

```dart
@Component()
class BookDocuments implements SearchDocumentSource {
  BookDocuments(this.books);

  final BookRepository books;

  @override
  Stream<SearchDocument> documents() async* {
    for (final book in await books.findAll()) {
      yield SearchDocument(
        id: 'book-${book.id}',
        fields: {'title': book.title, 'body': book.summary},
        link: '/books/${book.id}',
      );
    }
  }
}
```

## Languages

There is one index per language. A document's language is its own `language`, else `spring.search.default-language` (`en`). A search names its language (`search(query, language: 'ja')`); a language without documents searches the default language's, and `pt-BR` falls back to `pt` before that.

A source that knows its languages before it reads anything can implement `LanguageSearchDocumentSource` instead of `SearchDocumentSource`. The index of a language is built from `documentsIn(language)`, when that language is first searched:

```dart
@Component()
class ManualDocuments implements LanguageSearchDocumentSource {
  @override
  Set<String> get languages => {'en', 'ja'};

  @override
  Stream<SearchDocument> documentsIn(String language) => /* ... */;

  @override
  Stream<SearchDocument> documents() async* {
    for (final language in languages) {
      yield* documentsIn(language);
    }
  }
}
```

## Rebuilding the index

The index is built at the first search. When the documents change, publish a `SearchIndexInvalidatedEvent`; the next search reads the sources again:

```dart
@Service()
class BookAdmin {
  BookAdmin(this.books, this.events);

  final BookRepository books;
  final ApplicationEventPublisher events;

  Future<void> add(Book book) async {
    await books.save(book);
    events.publishEvent(SearchIndexInvalidatedEvent(this));
  }
}
```

`SearchService.invalidate()` does the same from code that holds the service.

## See also

- [Searching](searching.md)
- [Analyzers and rankers](analyzers.md)
- [All properties](properties.md)
