# Guidedog

[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [हिन्दी](README.hi.md) · [Español](README.es.md) · [Deutsch](README.de.md)

**एक बार लिखें। साफ़ समझाएँ। वेब और कागज़ पर प्रकाशित करें।**

Guidedog reStructuredText और Markdown से HTML दस्तावेज़ साइट और PDF पुस्तकें बनाता है। यह Odin में लिखा गया है। इसके रूपांतरण इंजन का नाम **Guidedoc** है और Typst PDF की पृष्ठ-सज्जा करता है। Python वातावरण या LaTeX स्थापित करने की ज़रूरत नहीं है।

लेखन की प्रक्रिया Sphinx से प्रेरित है, पर Guidedog एक स्वतंत्र प्रणाली है। कॉन्फ़िगरेशन घोषणात्मक TOML में होता है और API का स्थिर विश्लेषण होता है। Python कॉन्फ़िगरेशन या एक्सटेंशन कभी नहीं चलते। Sphinx से पूरी अनुकूलता लक्ष्य नहीं है।

## परियोजना शुरू करें

```sh
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
```

परियोजना में `conf.toml`, `index.rst`, `_templates/layout.html`, `_templates/book.typ` और `_static/` होते हैं। टेम्पलेट सामान्य फ़ाइलें हैं जिन्हें सीधे बदल सकते हैं। HTML में नेविगेशन, खोज, कोड हाइलाइटिंग, आरेख और समीकरण मिलते हैं। PDF में अध्याय, पार-संदर्भ, चित्र, इंडेक्स और भाषा के अनुसार टाइपसेटिंग मिलती है।

डिफ़ॉल्ट थीम हल्की है; गहरी या सिस्टम थीम भी चुन सकते हैं। मैनुअल के मुख्य पृष्ठ और रिपॉज़िटरी परिचय पर ब्राउज़र की भाषा चुनी जाती है। सहेजी गई पसंद पहले लागू होती है। किसी भाषा या अध्याय के सीधे लिंक की पसंद नहीं बदली जाती।

```sh
guidedog convert notes.md --to pdf --output notes.pdf
guidedog clean docs
guidedog migrate conf.py
```

## स्थापित करें

हर [रिलीज़](https://github.com/insanai/guidedog/releases) में Linux (x86-64 और ARM64), macOS (Apple silicon और Intel) और Windows (x86-64) के लिए एक आर्काइव है। हर आर्काइव में Typst, Graphviz और tree-sitter शामिल हैं, इसलिए साइट और पुस्तकें बनाने के लिए और कुछ स्थापित नहीं करना पड़ता। Linux को glibc 2.35 या नया और libcurl चाहिए; macOS को संस्करण 12 या नया। अपने सिस्टम का आर्काइव और `SHA256SUMS` डाउनलोड करें, फिर जाँचकर स्थापित करें:

```sh
sha256sum -c --ignore-missing SHA256SUMS      # macOS पर: shasum -a 256 -c --ignore-missing SHA256SUMS
tar -xzf guidedog-linux-amd64.tar.gz
sudo install guidedog-linux-amd64/guidedog /usr/local/bin/
```

macOS पर आधिकारिक [Guidedog Homebrew tap](https://github.com/insanai/homebrew-guidedog) से स्थापित करें। Homebrew आपके Apple silicon या Intel प्रोसेसर के लिए सही पैकेज चुनता है। यह tap Linux पर भी काम करता है:

```sh
brew tap insanai/guidedog
brew install insanai/guidedog/guidedog
guidedog --version
```

Windows पर आर्काइव को अनज़िप करें और उसके फ़ोल्डर को `PATH` में जोड़ें; Graphviz की DLL फ़ाइलें और `config8` को `guidedog.exe` के पास ही रहने दें। प्रोग्रामों पर कोड-हस्ताक्षर नहीं है: macOS पर ब्राउज़र से डाउनलोड की गई फ़ाइल का क्वारंटीन `xattr -d com.apple.quarantine guidedog` से हटाएँ। हर प्लेटफ़ॉर्म की सीमाएँ रिलीज़ नोट्स में लिखी हैं।

## स्रोत से बिल्ड करें

Odin `dev-2026-10` (`tools/install-toolchain.sh odin DIR` इसे डाउनलोड करके जाँचता है), एक C कंपाइलर, और Linux पर libcurl, expat और zlib के डेवलपमेंट पैकेज स्थापित करें। पहले नेटिव लाइब्रेरी बनाएँ, फिर Guidedog:

```sh
native/tree-sitter/build.sh
native/graphviz/build.sh
tools/release/build.sh
```

इसके बाद `build/guidedog` PDF के लिए स्थापित Typst 0.15.1 का उपयोग करता है। रिलीज़ की तरह Typst कंपाइलर को अंतर्निहित करने के लिए Rust और Cargo स्थापित करके चलाएँ:

```sh
native/typst_bridge/build.sh
tools/release/build.sh --release --typst-bridge
```

Windows पर Visual Studio के C++ टूल और LLVM के साथ Git Bash का उपयोग करें। Graphviz का Windows के लिए स्थिर बिल्ड नहीं है, इसलिए `build.sh` की जगह `native/graphviz/windows.sh` चलाएँ: यह Graphviz 16.1.0 की आधिकारिक DLL फ़ाइलें स्थापित करता है, जिन्हें `tools/release/build.sh` `build/guidedog.exe` के पास कॉपी करता है। `tools/release/suites.sh` टेस्ट सूट चलाता है, और [RELEASING.md](RELEASING.md) रिलीज़ की प्रक्रिया बताता है।

## Guidedog से अनुवाद

```sh
mkdir -p docs/manual/_editions
build/guidedog build -b gettext docs/manual docs/manual/locales/templates -W
build/guidedog intl update -p docs/manual/locales/templates \
    -l zh_CN -l ja -l ko -l hi -l es -l de docs/manual
build/guidedog intl stat -l zh_CN -l ja -l ko -l hi -l es -l de docs/manual
build/guidedog build -b html docs/manual docs/manual/_editions/de \
    -D language=de -D 'html_extra_path=[]' -W
```

PO फ़ाइलों में `msgstr` का अनुवाद लिखें और जाँचें। Guidedog POT निकालता है, कैटलॉग मिलाता है, प्रगति बताता है और हर भाषा का संस्करण बनाता है; अनुवाद खुद नहीं लिखता। कमांड, पथ, कोड, API नाम और संदर्भ लक्ष्य न बदलें। केवल मैनुअल और रिपॉज़िटरी परिचय का अनुवाद होता है; API और GDS अंग्रेज़ी में रहते हैं। सारे संस्करण और PDF जोड़ने के लिए [बिल्ड निर्देश](docs/manual/README.md) देखें।

GitHub पर ऊपर के लिंक से README की भाषा चुनें। भाषा का स्वतः चयन बनी हुई दस्तावेज़ वेबसाइट पर होता है।

## पढ़ें और एम्बेड करें

- [मैनुअल](docs/manual/index.rst): ट्यूटोरियल, विषय, व्यावहारिक काम, संदर्भ और आंतरिक संरचना।
- [API संदर्भ](docs/api/index.rst): Odin स्रोत से बनता है और मैनुअल PDF के परिशिष्ट में भी रहता है।
- [लाइब्रेरी गाइड](lib/README.md): कॉलर के कार्यक्षेत्र, मेमोरी और रूपांतरण उदाहरण।
- [टेम्पलेट](docs/manual/templates.rst): Jinja से HTML और Typst से पुस्तक का रूप बदलें।
- [GDS](docs/gds/README.md): क्रमांकित डिज़ाइन अभिलेख और कार्यान्वयन के निर्णय।
- [बीटा समीक्षा](docs/manual/evidence/beta-review-20261011.md): सुधार, सत्यापन, समर्थन की सीमा और रिलीज़ से पहले बचा काम।

Guidedoc कॉलर की दी हुई मेमोरी इस्तेमाल करता है और संरचित निदान लौटाता है। होस्ट फ़ाइल, बजट, कैश, प्रकाशन और मूल कंपाइलर सँभालता है। `--untrusted` क्षमताएँ सीमित करता है; यह प्रक्रिया का सैंडबॉक्स या सभी मूल संसाधनों की सीमा नहीं है। बीटा macOS और Linux पर भरोसेमंद दस्तावेज़ परियोजनाओं के लिए है।

## श्रेय और लाइसेंस

**Vikrant Rathore** ने इसे बनाया, **Ronak Rathore** और **Kanak Rathore** ने सहयोग दिया। इश्यू और पुल रिक्वेस्ट के ज़रिए योगदान का स्वागत है। दस्तावेज़ में नाम या हैंडल दिए जाते हैं, निजी ईमेल पते नहीं। Git की पहचान संबंधी सेटिंग अलग सँभाली जाती हैं।

Sphinx और Georg Brandl, Docutils और David Goodger, Typst, Tree-sitter और Max Brunsfeld, Graphviz तथा Ginger Bill और Odin समुदाय का धन्यवाद।

Guidedog [GNU Affero General Public License v3.0 या उसके बाद के संस्करण](LICENSE) (AGPL-3.0-or-later) के अंतर्गत जारी किया गया है। अन्य लाइसेंस शर्तों के लिए लेखकों से संपर्क करें। संपर्क का तरीका [NOTICE](NOTICE) में दिया गया है, साथ ही उन तृतीय-पक्ष घटकों की सूची भी, जिनके अपने लाइसेंस रहते हैं, जैसे शामिल फ़ॉन्ट। एक अतिरिक्त अनुमति Guidedog को Graphviz के साथ लिंक करने और वितरित करने देती है; देखें [NOTICE](NOTICE)।