Skip to Content
DocumentationGuidesCreating Documents

Creating Documents

This guide covers building GLOST documents from scratch.

Quick Start: Simplified Helpers

For most use cases, use these simplified helper functions:

createSimpleDocument() - One-Step Document Creation

The easiest way to create a GLOST document from words:

import { createSimpleDocument } from '@glotblocks/glost'; import { createThaiWord } from '@glotblocks/glost-th'; const words = [ createThaiWord({ text: "สวัสดี" }), createThaiWord({ text: "ครับ" }) ]; // Creates complete document with one function call const document = createSimpleDocument(words, "th", "thai", { sentenceText: "สวัสดีครับ", metadata: { title: "Greeting" } });

When to use: Tests, prototypes, simple documents, or when you don’t need explicit paragraph/sentence structure.

createDocumentFromSentences() - Skip Paragraph Wrapper

When you have sentences but don’t need paragraph structure:

import { createDocumentFromSentences, createSentenceFromWords } from '@glotblocks/glost'; const sentence1 = createSentenceFromWords(words1, "th", "thai", "สวัสดี"); const sentence2 = createSentenceFromWords(words2, "th", "thai", "ขอบคุณ"); const document = createDocumentFromSentences( [sentence1, sentence2], "th", "thai", { title: "Lesson 1" } );

When to use: When you already have sentences but want minimal boilerplate.

Before/After Comparison

Before (Verbose):

const sentence = createSentenceFromWords(words, "th", "thai", "สวัสดี"); const paragraph = createParagraphFromSentences([sentence]); const doc = createDocumentFromParagraphs([paragraph], "th", "thai");

After (Simplified):

const doc = createSimpleDocument(words, "th", "thai", { sentenceText: "สวัสดี" });

Result: ~60% less code!


Document Structure

A GLOST document has this hierarchy:

GLOSTRoot (document) ├── GLOSTParagraph │ └── GLOSTSentence │ ├── GLOSTWord │ ├── GLOSTWhiteSpace │ └── GLOSTPunctuation

Creating Words

Basic Word

import { createGLOSTWordNode } from '@glotblocks/glost'; const word = createGLOSTWordNode({ value: "hello", transcription: { ipa: { text: "heloʊ" } }, metadata: { partOfSpeech: "interjection" }, lang: "en", script: "latin", extras: { translations: { th: "สวัสดี" } } });

Simple Word

When you just need text and transcription:

import { createSimpleWord } from '@glotblocks/glost'; const word = createSimpleWord({ text: "hello", transliteration: "heloʊ", system: "ipa" });

Thai Word

With RTGS romanization:

import { createThaiWord } from '@glotblocks/glost-th'; const word = createThaiWord({ text: "สวัสดี", rtgs: "sawatdi", partOfSpeech: "interjection", tone: 2, syllables: ["sa", "wat", "di"] });

Japanese Word

With romaji and furigana:

import { createJapaneseWord } from '@glotblocks/glost-ja'; const word = createJapaneseWord({ text: "今日", romaji: "kyou", partOfSpeech: "noun", furigana: "きょう" });

Creating Sentences

From Words

import { createSentenceFromWords } from '@glotblocks/glost'; import { createThaiWord } from '@glotblocks/glost-th'; const words = [ createThaiWord({ text: "สวัสดี", rtgs: "sawatdi", partOfSpeech: "interjection" }), createThaiWord({ text: "ครับ", rtgs: "khrap", partOfSpeech: "particle" }) ]; const sentence = createSentenceFromWords( words, "th", // language "thai", // script "สวัสดีครับ" // original text );

Manual Construction

For more control over whitespace and punctuation:

import { createGLOSTSentenceNode, createGLOSTWordNode, createGLOSTWhiteSpaceNode, createGLOSTPunctuationNode } from '@glotblocks/glost'; const sentence = createGLOSTSentenceNode({ originalText: "Hello, world!", lang: "en", script: "latin", children: [ createGLOSTWordNode({ value: "Hello", metadata: { partOfSpeech: "interjection" } }), createGLOSTPunctuationNode(","), createGLOSTWhiteSpaceNode(" "), createGLOSTWordNode({ value: "world", metadata: { partOfSpeech: "noun" } }), createGLOSTPunctuationNode("!") ] });

Creating Paragraphs

import { createParagraphFromSentences, createGLOSTParagraphNode } from '@glotblocks/glost'; // From sentences helper const paragraph = createParagraphFromSentences([sentence1, sentence2]); // Or manual const paragraph = createGLOSTParagraphNode([sentence1, sentence2]);

Creating Documents

From Paragraphs

import { createDocumentFromParagraphs } from '@glotblocks/glost'; const document = createDocumentFromParagraphs( [paragraph1, paragraph2], "th", // language "thai", // script { title: "Lesson 1" } // metadata );

Manual Construction

import { createGLOSTRootNode } from '@glotblocks/glost'; const document = createGLOSTRootNode({ lang: "th", script: "thai", children: [paragraph], metadata: { title: "Lesson 1", author: "John" }, extras: { customField: "value" } });

Adding Rich Metadata

Word Translations

import { createGLOSTWordNode } from '@glotblocks/glost'; const word = createGLOSTWordNode({ value: "สวัสดี", transcription: { rtgs: { text: "sawatdi" } }, metadata: { partOfSpeech: "interjection" }, lang: "th", script: "thai", extras: { translations: { en: "hello", ja: "こんにちは", zh: "你好" } } });

Extended Metadata

import { createGLOSTWordNode } from '@glotblocks/glost'; const word = createGLOSTWordNode({ value: "สวัสดี", transcription: { rtgs: { text: "sawatdi" } }, metadata: { partOfSpeech: "interjection", formality: "formal" }, lang: "th", script: "thai", extras: { translations: { en: "hello" }, metadata: { difficulty: "beginner", frequency: "very-common", culturalNotes: "Used as a greeting any time of day", related: ["สวัสดีค่ะ", "หวัดดี"], examples: ["สวัสดีครับ ผมชื่อจอห์น"] } } });

Multiple Transcriptions

import { createGLOSTWordNode } from '@glotblocks/glost'; const word = createGLOSTWordNode({ value: "สวัสดี", transcription: { rtgs: { text: "sawatdi" }, ipa: { text: "sa.wàt.diː" }, paiboon: { text: "sa-wat-dii", syllables: ["sa", "wat", "dii"], tone: 2 } }, metadata: { partOfSpeech: "interjection" }, lang: "th", script: "thai" });

Best Practices

  1. Always set language - Even if it seems obvious
  2. Use original text - Store the original in sentences
  3. Add transcriptions early - They’re useful for processing
  4. Be consistent with metadata - Use the same fields across words
  5. Preserve whitespace - It matters for display
Last updated on