What is a Directed Acyclic Graph (DAG)?
Was this page helpful?
`; var content = document.querySelector('.md-content__inner'); if (content) { content.appendChild(feedback); } feedback.querySelectorAll('.feedback-btn').forEach(function(btn) { btn.addEventListener('click', function() { var value = this.dataset.value; // Send to analytics or backend console.log('Feedback:', value, 'Page:', window.location.pathname); // Optional: Send to Google Analytics if (typeof gtag !== 'undefined') { gtag('event', 'page_feedback', { 'event_category': 'feedback', 'event_label': window.location.pathname, 'value': value === 'yes' ? 1 : 0 }); } feedback.querySelectorAll('.feedback-btn').forEach(function(b) { b.style.display = 'none'; }); feedback.querySelector('.feedback-thanks').style.display = 'inline'; }); }); }); ``` **Create `docs/css/feedback.css`:** ```css .page-feedback { margin-top: 2rem; padding: 1rem; background: var(--md-code-bg-color); border-radius: 8px; text-align: center; } .feedback-btn { padding: 0.5rem 1rem; margin: 0 0.5rem; border: none; border-radius: 4px; cursor: pointer; font-size: 1rem; background: var(--md-primary-fg-color); color: var(--md-primary-bg-color); } .feedback-btn:hover { opacity: 0.8; } .feedback-thanks { color: var(--md-accent-fg-color); font-weight: bold; } ``` --- ### Detailed Comment Feedback (Giscus) Enable GitHub Discussions-powered comments using Giscus. **Prerequisites:** 1. Enable GitHub Discussions on your repository 2. Install Giscus app: https://github.com/apps/giscus 3. Configure at: https://giscus.app **Add to mkdocs.yml:** ```yaml extra: giscus: repo: "username/repo-name" repo_id: "R_xxxxx" category: "Announcements" category_id: "DIC_xxxxx" mapping: "pathname" reactions_enabled: "1" emit_metadata: "0" theme: "preferred_color_scheme" lang: "en" ``` **Create `docs/javascripts/giscus.js`:** ```javascript document$.subscribe(function() { var container = document.createElement('div'); container.className = 'giscus-container'; var content = document.querySelector('.md-content__inner'); if (content && !document.querySelector('.giscus')) { content.appendChild(container); var script = document.createElement('script'); script.src = 'https://giscus.app/client.js'; script.dataset.repo = '{{ config.extra.giscus.repo }}'; script.dataset.repoId = '{{ config.extra.giscus.repo_id }}'; script.dataset.category = '{{ config.extra.giscus.category }}'; script.dataset.categoryId = '{{ config.extra.giscus.category_id }}'; script.dataset.mapping = '{{ config.extra.giscus.mapping }}'; script.dataset.reactionsEnabled = '{{ config.extra.giscus.reactions_enabled }}'; script.dataset.emitMetadata = '{{ config.extra.giscus.emit_metadata }}'; script.dataset.theme = '{{ config.extra.giscus.theme }}'; script.dataset.lang = '{{ config.extra.giscus.lang }}'; script.crossOrigin = 'anonymous'; script.async = true; container.appendChild(script); } }); ``` **Add to mkdocs.yml:** ```yaml extra_javascript: - javascripts/giscus.js ``` --- ### Image Zoom on Click (GLightbox) Enable lightbox zoom for images when clicked. **Install:** `pip install mkdocs-glightbox` **Add to mkdocs.yml:** ```yaml plugins: - glightbox: touchNavigation: true loop: false effect: zoom slide_effect: slide width: 100% height: auto zoomable: true draggable: true auto_caption: false caption_position: bottom ``` All images will now be zoomable on click. To exclude specific images: ```markdown { .off-glb } ``` --- ## Navigation Features > **Important:** Do NOT use `navigation.tabs` or `navigation.tabs.sticky` in mkdocs.yml. > These books are designed for wide landscape screens with ample side navigation space. > If you see these settings in an existing mkdocs.yml, remove them. ### Table of Contents Sidebar Configure the right-side table of contents. **Add to mkdocs.yml:** ```yaml theme: name: material features: - navigation.indexes - toc.follow - toc.integrate # Integrate TOC into left sidebar markdown_extensions: - toc: permalink: true toc_depth: 3 ``` --- ### Search with Suggestions Enable advanced search with suggestions and highlighting. **Add to mkdocs.yml:** ```yaml plugins: - search: separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;' theme: name: material features: - search.suggest - search.highlight - search.share ``` --- ## Organization Features ### Tags & Categorization Add tags to pages for categorization and filtering. **Add to mkdocs.yml:** ```yaml plugins: - tags: tags_file: tags.md markdown_extensions: - meta ``` **Create `docs/tags.md`:** ```markdown # Tags [TAGS] ``` **Usage in page frontmatter:** ```yaml --- tags: - learning-graph - educational - beginner --- ``` --- ### Blog Support Add a blog section to your documentation. **Add to mkdocs.yml:** ```yaml plugins: - blog: blog_dir: blog post_date_format: long archive_name: Archive categories_name: Categories ``` **Create `docs/blog/.authors.yml`:** ```yaml authors: author_name: name: Author Name description: Author description avatar: https://github.com/username.png ``` --- ## Legal & Compliance ### Privacy & Cookie Consent Add GDPR-compliant cookie consent banner. **Add to mkdocs.yml:** ```yaml extra: consent: title: Cookie consent description: >- We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better. actions: - accept - reject - manage ``` --- ### Announcement Bar Add a dismissible announcement banner at the top of pages. **Add to mkdocs.yml:** ```yaml theme: name: material custom_dir: overrides extra: announcement: "π New version 2.0 released! See what's new" ``` **Create `overrides/main.html`:** ```html {% extends "base.html" %} {% block announce %} {{ config.extra.announcement | safe }} {% endblock %} ``` --- ## How to Use This Guide 1. **Identify the feature** you want to add from the table above 2. **Read the prerequisites** - some features require pip packages 3. **Copy the mkdocs.yml configuration** to your project 4. **Create any required files** (JavaScript, CSS, templates) 5. **Test locally** with `mkdocs serve` 6. **Deploy** when satisfied ## Minimal to Full-Featured Workflow If starting with a minimal mkdocs.yml, add features incrementally: 1. **Essential first:** Code highlighting, admonitions, math 2. **Navigation:** Search, TOC, tabs 3. **SEO:** Social cards, meta tags 4. **Engagement:** Feedback, comments 5. **Educational:** Quizzes, interactive elements ## Troubleshooting ### Remove navigation tabs if present These intelligent textbooks use side navigation optimized for wide landscape screens. If you find `navigation.tabs` in mkdocs.yml, remove it: ```yaml # REMOVE these lines if present: theme: features: - navigation.tabs # DELETE - navigation.tabs.sticky # DELETE ``` ### Feature not working? 1. Check that all required extensions are listed in `markdown_extensions` 2. Verify JavaScript/CSS files are in correct locations 3. Clear browser cache and MkDocs cache (`mkdocs build --clean`) 4. Check browser console for JavaScript errors ### Plugin conflicts? Order plugins carefully in mkdocs.yml - some plugins must come before others: ```yaml plugins: - search # Usually first - social_override # Before social - social - tags - glightbox ```