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
│ └── GLOSTPunctuationCreating 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
- Always set language - Even if it seems obvious
- Use original text - Store the original in sentences
- Add transcriptions early - They’re useful for processing
- Be consistent with metadata - Use the same fields across words
- Preserve whitespace - It matters for display
Last updated on