# Markdigille rakennetaan kauko-ohjattava fetcher

<!--category-- Markdown, AI-Article,  MarkDig, ASP.NET Core, C#, API, Nuget, FetchExtension-->
<datetime class="hidden">2025-11-07T10:00</datetime>

# Johdanto

Yksi haasteita, joita jouduin kohtaamaan tätä blogia rakennettaessa, oli se, miten ulkoiset markown-sisällöt saadaan tehokkaasti mukaan kopioimatta ja liittämättä niitä käsin kaikkialle.

Halusin hakea README-tiedostoja GitHub-arkistoistani, sisältää asiakirjoja muista projekteista ja pitää kaiken automaattisesti synkronoituna.`Mostlylucid.Markdig.FetchExtension`Mikä on ratkaisu?

> Räätälöity Markdig-laajennus, joka hakee etäleimauksen ja tallentaa sen älykkäästi.

> Tässä viestissä kerron, miten rakensin

> **- täydellinen ratkaisu kauko-ohjattavan maalintekosisällön hakemiseen ja välimuistiin useiden säilytystallenteiden, automaattisten äänestysten ja vanhentuneen välimuistikuvion avulla.**HUOMAUTUS: Tämä on vielä ennakkojulkaisu, mutta halusin saada sen julki.`disable="true"`Pidä hauskaa, mutta se ei ehkä toimi vielä.

> **Tämä artikkeli on tekoäly luotu - käyttäen laudan koodia, joka myös auttoi minua rakentamaan ominaisuuden.**PÄIVITYS`[TOC]`: Lisätty

Parametri, jotta voimme nyt demota tunnisteet kunnolla ilman, että niitä käsitellään![PÄIVITYS (7. marraskuuta 2025)](https://github.com/scottgal/mostlylucidweb/tree/main/Mostlylucid.Markdig.FetchExtension).

[![: Lisätty Sisällysluettelo (TOC) sukupolven ominaisuus!](https://img.shields.io/nuget/v/mostlylucid.Markdig.FetchExtension.svg)](https://www.nuget.org/packages/mostlylucid.Markdig.FetchExtension)
[![Käyttö](https://img.shields.io/nuget/dt/mostlylucid.Markdig.FetchExtension.svg)](https://www.nuget.org/packages/mostlylucid.Markdig.FetchExtension)

[TOC]

# Merkinnässäsi luot automaattisesti klikattavan sisällystaulukon asiakirjojen otsikoista.

Katso lähde täältä

1. **on the GitHub tälle sivustolle**NuGet
2. **NuGet**Miksi rakentaa tätä?
3. **Ennen kuin syvennytään teknisiin yksityiskohtiin, selitän ongelman.**Minulla on useita skenaarioita, joissa minun on sisällytettävä ulkoiset markown-sisällöt:
4. **Package READMEs -paketti**: Kun kirjoitan julkaisemastani NuGet-paketista, haluan liittää mukaan sen READMEn suoraan GitHubista

API-dokumentaatio

- : Ulkoisen API-dokumentin, joka muuttuu usein, on pysyttävä ajan tasalla
- Jaettu sisältö
- : Dokumentaatio, joka asuu yhdessä arkistossa, mutta jota tarvitaan useissa paikoissa
- Suorituskyky

: En halua hakea tätä sisältöä jokaisesta sivukuormasta - se olisi hidasta ja tuhlailevaa

# Naiivi lähestymistapa olisi käyttää HTTP asiakas noutaa markdown aina, kun tarvitset sitä.

Mutta se on ongelmallista:

```mermaid
graph TD
    A[Markdown with fetch tags] --> B[MarkdownFetchPreprocessor]
    B --> C{Check Cache}
    C -->|Fresh| D[Return Cached Content]
    C -->|Stale/Missing| E[Fetch from Remote URL]
    E -->|Success| F[Update Cache]
    E -->|Failure| G{Has Cached?}
    G -->|Yes| H[Return Stale Cache]
    G -->|No| I[Return Error Comment]
    F --> J[Replace fetch with Content]
    D --> J
    H --> J
    I --> J
    J --> K[Processed Markdown]
    K --> L[Your Markdig Pipeline]
    L --> M[Final HTML]

```

Jokainen pyyntö osuu etäpalvelimeen**Verkon latenssi vaikuttaa sivujen latausaikoihin**Ei offline-tukea

1. Ohimeneviä vikoja ei käsitellä`<fetch>`Tarvitsin jotain fiksumpaa: nouta kerran, välimuisti älykkäästi, virkistä automaattisesti ja käsittele epäonnistumiset sulavasti.
2. Arkkitehtuurin yleiskatsaus
3. Laajennus noudattaa esikäsittelyä sen sijaan, että se olisi osa Markdigin jäsennysputkea.
4. Tämä on ratkaisevan tärkeää, koska se tarkoittaa, että haussa oleva sisältö virtaa koko Markdigin putkiston läpi ja saa kaikki mukautetut laajennukset, syntaksin korostuksen ja muotoilun.

Avainnäkemys tässä on

# esikäsittely



```markdown
# My Documentation

<fetch markdownurl="https://raw.githubusercontent.com/user/repo/main/README.md"
       pollfrequency="24" disable="true"/>
```

Ennen kuin maali putoaa Markdigin putkeen, me:

- Skannaa
- tunnisteet
- Ratkaise sisältö (välimuistista tai etänä)
- Korvaa tagit todellisella markdownilla

# Anna Markdigin sitten käsitellä kaikki yhdessä.

Tämä takaa johdonmukaisuuden - kaikki markdownit saavat saman kohtelun lähteestään riippumatta.**Perussyntaksi**Laajennuksen käyttö on yksinkertaista.

```mermaid
graph LR
    A[IMarkdownFetchService Interface] --> B[InMemoryMarkdownFetchService]
    A --> C[FileBasedMarkdownFetchService]
    A --> D[PostgresMarkdownFetchService]
    A --> E[SqliteMarkdownFetchService]
    A --> F[SqlServerMarkdownFetchService]
    A --> G[YourCustomService]

    B --> H[ConcurrentDictionary]
    C --> I[File System + SemaphoreSlim]
    D --> J[PostgreSQL Database]
    E --> K[SQLite Database]
    F --> L[SQL Server Database]
    G --> M[Your Storage Backend]

```

## Paikoillanne:

Juuri noin!`IMarkdownFetchService`:

```csharp
public interface IMarkdownFetchService
{
    Task<MarkdownFetchResult> FetchMarkdownAsync(
        string url,
        int pollFrequencyHours,
        int blogPostId = 0);

    Task<bool> RemoveCachedMarkdownAsync(
        string url,
        int blogPostId = 0);
}
```

Laajennus tulee olemaan seuraava:

## Hae LUEME GitHubista

Viipaloi sitä 24 tuntia`ConcurrentDictionary`:

```csharp
public class InMemoryMarkdownFetchService : IMarkdownFetchService
{
    private readonly ConcurrentDictionary<string, CacheEntry> _cache = new();
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<InMemoryMarkdownFetchService> _logger;

    public async Task<MarkdownFetchResult> FetchMarkdownAsync(
        string url,
        int pollFrequencyHours,
        int blogPostId)
    {
        var cacheKey = GetCacheKey(url, blogPostId);

        // Check cache
        if (_cache.TryGetValue(cacheKey, out var cached))
        {
            var age = DateTimeOffset.UtcNow - cached.FetchedAt;
            if (age.TotalHours < pollFrequencyHours)
            {
                _logger.LogDebug("Returning cached content for {Url}", url);
                return new MarkdownFetchResult
                {
                    Success = true,
                    Content = cached.Content
                };
            }
        }

        // Fetch fresh content
        var fetchResult = await FetchFromUrlAsync(url);

        if (fetchResult.Success)
        {
            _cache[cacheKey] = new CacheEntry
            {
                Content = fetchResult.Content,
                FetchedAt = DateTimeOffset.UtcNow
            };
        }
        else if (cached != null)
        {
            // Fetch failed, return stale cache
            _logger.LogWarning("Fetch failed, returning stale cache for {Url}", url);
            return new MarkdownFetchResult
            {
                Success = true,
                Content = cached.Content
            };
        }

        return fetchResult;
    }

    private static string GetCacheKey(string url, int blogPostId)
        => $"{url}_{blogPostId}";
}
```

Palauta välimuistiin tallennettua sisältöä seuraavissa pyynnöissä

1. Päivitä automaattisesti, kun välimuisti päättyy
2. Varastontarjoajan arkkitehtuuri
3. Yksi noudattamistani suunnitteluperiaatteista oli
4. joustot
5. 
6. Erilaisilla sovelluksilla on erilaiset tarpeet.
7. Pieni demosovellus ei tarvitse PostgreSQL:ää, mutta monipalvelintuotannon käyttöönotto vaatii.

Niinpä rakensin tukittavan säilytysarkkitehtuurin:**Ydinliitännät**Kaikki toimii

## Yksinkertaista ja puhdasta.

Jokainen toteutus käsittelee tallennuksen omalla tavallaan, mutta rajapinta pysyy johdonmukaisena.

```csharp
public class FileBasedMarkdownFetchService : IMarkdownFetchService
{
    private readonly string _cacheDirectory;
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<FileBasedMarkdownFetchService> _logger;
    private readonly SemaphoreSlim _fileLock = new(1, 1);

    public async Task<MarkdownFetchResult> FetchMarkdownAsync(
        string url,
        int pollFrequencyHours,
        int blogPostId)
    {
        var cacheKey = ComputeCacheKey(url, blogPostId);
        var cacheFile = GetCacheFilePath(cacheKey);

        await _fileLock.WaitAsync();
        try
        {
            // Check if file exists and is fresh
            if (File.Exists(cacheFile))
            {
                var fileInfo = new FileInfo(cacheFile);
                var age = DateTimeOffset.UtcNow - fileInfo.LastWriteTimeUtc;

                if (age.TotalHours < pollFrequencyHours)
                {
                    var cached = await File.ReadAllTextAsync(cacheFile);
                    return new MarkdownFetchResult
                    {
                        Success = true,
                        Content = cached
                    };
                }
            }

            // Fetch fresh
            var fetchResult = await FetchFromUrlAsync(url);

            if (fetchResult.Success)
            {
                await File.WriteAllTextAsync(cacheFile, fetchResult.Content);
            }
            else if (File.Exists(cacheFile))
            {
                // Return stale on fetch failure
                var stale = await File.ReadAllTextAsync(cacheFile);
                return new MarkdownFetchResult
                {
                    Success = true,
                    Content = stale
                };
            }

            return fetchResult;
        }
        finally
        {
            _fileLock.Release();
        }
    }

    private string GetCacheFilePath(string cacheKey)
        => Path.Combine(_cacheDirectory, $"{cacheKey}.md");

    private static string ComputeCacheKey(string url, int blogPostId)
    {
        var combined = $"{url}_{blogPostId}";
        using var sha256 = SHA256.Create();
        var bytes = Encoding.UTF8.GetBytes(combined);
        var hash = sha256.ComputeHash(bytes);
        return Convert.ToHexString(hash);
    }
}
```

In-Memory Storage: Perfect for Demos

1. Yksinkertaisin toteutuskäyttö`SemaphoreSlim`Kuten näette, tämä toimii seuraavasti:
2. Luo välimuistiavaimen URL-osoitteesta ja blogikirjoituksesta
3. Tarkistaa, onko meillä välimuistissa sisältöä ja onko se tuoretta
4. Jos välimuisti on tuore, palauta se välittömästi
5. Jos olet tunkkainen, yritä hakea tuoretta sisältöä

## Onnistumisen yhteydessä päivitä välimuisti

Jos epäonnistut välimuistin sisällön kanssa, palautat tahmean välimuistin (tila-aika-aika-aika-aika!)

```csharp
public class PostgresMarkdownFetchService : IMarkdownFetchService
{
    private readonly MarkdownCacheDbContext _dbContext;
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<PostgresMarkdownFetchService> _logger;

    public async Task<MarkdownFetchResult> FetchMarkdownAsync(
        string url,
        int pollFrequencyHours,
        int blogPostId)
    {
        var cacheKey = GetCacheKey(url, blogPostId);

        // Query cache
        var cached = await _dbContext.MarkdownCache
            .FirstOrDefaultAsync(c => c.CacheKey == cacheKey);

        if (cached != null)
        {
            var age = DateTimeOffset.UtcNow - cached.LastFetchedAt;
            if (age.TotalHours < pollFrequencyHours)
            {
                return new MarkdownFetchResult
                {
                    Success = true,
                    Content = cached.Content
                };
            }
        }

        // Fetch fresh
        var fetchResult = await FetchFromUrlAsync(url);

        if (fetchResult.Success)
        {
            if (cached == null)
            {
                cached = new MarkdownCacheEntry
                {
                    CacheKey = cacheKey,
                    Url = url,
                    BlogPostId = blogPostId
                };
                _dbContext.MarkdownCache.Add(cached);
            }

            cached.Content = fetchResult.Content;
            cached.LastFetchedAt = DateTimeOffset.UtcNow;
            await _dbContext.SaveChangesAsync();
        }
        else if (cached != null)
        {
            // Return stale
            return new MarkdownFetchResult
            {
                Success = true,
                Content = cached.Content
            };
        }

        return fetchResult;
    }
}
```

Virheelle ilman välimuistia, palauttaa virheen

```sql
CREATE TABLE markdown_cache (
    id SERIAL PRIMARY KEY,
    cache_key VARCHAR(128) NOT NULL UNIQUE,
    url VARCHAR(2048) NOT NULL,
    blog_post_id INTEGER NOT NULL,
    content TEXT NOT NULL,
    last_fetched_at TIMESTAMP WITH TIME ZONE NOT NULL,
    CONSTRAINT ix_markdown_cache_cache_key UNIQUE (cache_key)
);

CREATE INDEX ix_markdown_cache_url_blog_post_id
    ON markdown_cache(url, blog_post_id);
```

Tämä kuvio...

```mermaid
graph TB
    subgraph "Load Balancer"
        LB[Load Balancer]
    end

    subgraph "Application Servers"
        A1[App Server 1<br/>FetchExtension]
        A2[App Server 2<br/>FetchExtension]
        A3[App Server 3<br/>FetchExtension]
    end

    subgraph "Shared Cache"
        PG[(PostgreSQL<br/>markdown_cache table)]
    end

    subgraph "External Content"
        R1[Remote URL 1]
        R2[Remote URL 2]
        R3[Remote URL 3]
    end

    LB --> A1
    LB --> A2
    LB --> A3

    A1 <-->|Read/Write Cache| PG
    A2 <-->|Read/Write Cache| PG
    A3 <-->|Read/Write Cache| PG

    A1 -.->|Fetch if cache miss| R1
    A2 -.->|Fetch if cache miss| R2
    A3 -.->|Fetch if cache miss| R3

```

vanhentunut voimassaoloajan pidentäminen

# - Se on ratkaisevaa luotettavuudelle.

Vaikka GitHub olisi alhaalla, sivustosi jatkaa työskentelyään välimuistin sisällön kanssa.

```bash
dotnet add package mostlylucid.Markdig.FetchExtension
```

Tiedostopohjainen säilytys: yksinkertainen pysyvyys

```bash
# For in-memory (demos/testing)
# Already included in base package

# For file-based storage
# Already included in base package

# For PostgreSQL
dotnet add package mostlylucid.Markdig.FetchExtension.Postgres

# For SQLite
dotnet add package mostlylucid.Markdig.FetchExtension.Sqlite

# For SQL Server
dotnet add package mostlylucid.Markdig.FetchExtension.SqlServer
```

## Yhden palvelimen käyttöönotoissa tiedostopohjainen tallennus toimii erinomaisesti:

Tärkeimmät kohdat tässä:`Program.cs`:

```csharp
using Mostlylucid.Markdig.FetchExtension;

var builder = WebApplication.CreateBuilder(args);

// Option 1: In-Memory (simplest)
builder.Services.AddInMemoryMarkdownFetch();

// Option 2: File-Based (persists across restarts)
builder.Services.AddFileBasedMarkdownFetch("./markdown-cache");

// Option 3: PostgreSQL (multi-server)
builder.Services.AddPostgresMarkdownFetch(
    builder.Configuration.GetConnectionString("MarkdownCache"));

// Option 4: SQLite (single server with DB)
builder.Services.AddSqliteMarkdownFetch("Data Source=markdown-cache.db");

// Option 5: SQL Server (enterprise)
builder.Services.AddSqlServerMarkdownFetch(
    builder.Configuration.GetConnectionString("MarkdownCache"));

var app = builder.Build();

// If using database storage, ensure schema exists
if (app.Environment.IsDevelopment())
{
    app.Services.EnsureMarkdownCacheDatabase();
}

// Configure the extension with your service provider
FetchMarkdownExtension.ConfigureServiceProvider(app.Services);

app.Run();
```

## Käyttö

langanvarmalle tiedostolle pääsylle

```csharp
public class MarkdownRenderingService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly MarkdownFetchPreprocessor _preprocessor;
    private readonly MarkdownPipeline _pipeline;

    public MarkdownRenderingService(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
        _preprocessor = new MarkdownFetchPreprocessor(serviceProvider);

        _pipeline = new MarkdownPipelineBuilder()
            .UseAdvancedExtensions()
            .UseSyntaxHighlighting()
            .UseToc()  // Add TOC support for [TOC] markers
            .UseYourCustomExtensions()
            .Build();
    }

    public string RenderMarkdown(string markdown)
    {
        // Step 1: Preprocess to handle fetch tags
        var processed = _preprocessor.Preprocess(markdown);

        // Step 2: Run through your normal Markdig pipeline
        return Markdown.ToHtml(processed, _pipeline);
    }
}
```

Hashes URL + blogikirjoitus ID luoda turvallisia tiedostonimiä

1. Käyttää tiedostojen muokkausaikaa tuoreuden määrittämiseen`<fetch>`Kestää koko sovelluksen uudelleenkäynnistykset
2. Sama vanhentunut uudelleenvalidointimalli
3. Tietokantavarasto: Production-Ready
4. Tuotannon käyttöönotoissa, erityisesti monipalvelinasetuksissa, haluat yhteisen välimuistin.

# Siinä tietokannan tarjoajat tulevat kuvaan:

## Tietokantaskeema on yksinkertainen:

Monipalvelimen käyttöönotossa tämä antaa sinulle välimuistin johdonmukaisuuden kaikissa tapauksissa:**Kaikki palvelimet jakavat saman välimuistin.**Kun Server 1 hakee README:n, palvelimet 2 ja 3 hyötyvät välittömästi välimuistisisällöstä.

**Laajennuksen pystyttäminen**

Aloittaminen on yksinkertaista.`[TOC]`Asenna ensin peruspaketti:

```markdown
# My Document

[TOC]

# Introduction
Content here...

# Getting Started
More content...

## Installation
Details...
```

Valitse sitten varastonpitäjäsi:

```html
<nav class="ml_toc" aria-label="Table of Contents">
  <ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#getting-started">Getting Started</a>
      <ul>
        <li><a href="#installation">Installation</a></li>
      </ul>
    </li>
  </ul>
</nav>
```

**Asetukset ASP.NET-ytimessä**

• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

```markdown
[TOC cssclass="my-custom-toc"]
```

Integrointi Markdown Renderointiin

```html
<nav class="my-custom-toc" aria-label="Table of Contents">
  <!-- TOC content -->
</nav>
```

**Avain on esikäsittelyvaihe.**

1. **Näin liitän sen blogiini:**Virtaus on:

2. **Markdown sisältää**tunnisteet
   
   - Esiprosessori määrää ne varsinaiseen markdowniin`id="getting-started"`
   - Yhdistetty markkalasku kulkee Markdigin kautta`id="api-reference"`

3. **Kaikki saa custom-laajennuksia, muotoilua jne.**Kehittyneet ominaisuudet`ul/li`Sisällysluettelon laatiminen

**Paketissa on nyt**

erillinen

```csharp
var pipeline = new MarkdownPipelineBuilder()
    .UseAdvancedExtensions()
    .UseToc()  // Add TOC support - position in pipeline doesn't matter!
    .Use<YourOtherExtensions>()
    .Build();
```

**Sisällysluettelon laajennus!**Vaikka se on pakattu noutolaajennuksen rinnalle, se on täysin itsenäinen ja sitä voidaan käyttää yksin.**Asiakirjan otsikoista voi automaattisesti luoda klikattavan sisällystaulukon.**Peruskäyttö:

- Lisää yksinkertaisesti
- missä tahansa maaliviivalla:

Näin saadaan pesitty lista kaikista otsikoista, joissa on ankkurilenkit:`.UseToc()`Omat CSS-luokat:

**Voit määritellä CSS-luokan tyylittelyyn:**Tämä on custom-luokallasi:

- Miten se toimii:
- Automaattinen detektio
- : TOC havaitsee automaattisesti asiakirjasi vähimmäissuuntatason ja säätää sen mukaan.

**Jos asiakirjasi alkaa H2:lla, TOC pitää H2:ta huipputasona.**ID-sukupolvi`[TOC]`: Otsikot annetaan automaattisesti ankkureille, jotka yhdistävät:`.UseToc()`"Aloitetaan" →

## "API-viite" →

Nested Structure

```markdown
<fetch markdownurl="https://raw.githubusercontent.com/user/repo/main/docs/README.md"
       pollfrequency="24"
       transformlinks="true" disable="true"/>
```

: Renderaattori rakentaa kunnolla pesivän

- `./CONTRIBUTING.md` → `https://github.com/user/repo/blob/main/docs/CONTRIBUTING.md`
- `../images/logo.png` → `https://github.com/user/repo/blob/main/images/logo.png`
- rakenne, joka heijastaa asiakirjahierarkiaasi.

Mahdollinen TOC-tuki:

```csharp
public class MarkdownLinkRewriter
{
    public static string RewriteLinks(string markdown, string sourceUrl)
    {
        var document = Markdown.Parse(markdown);
        var baseUri = GetBaseUri(sourceUrl);

        foreach (var link in document.Descendants<LinkInline>())
        {
            if (IsRelativeLink(link.Url))
            {
                link.Url = ResolveRelativeLink(baseUri, link.Url);
            }
        }

        using var writer = new StringWriter();
        var renderer = new NormalizeRenderer(writer);
        renderer.Render(document);
        return writer.ToString();
    }

    private static bool IsRelativeLink(string url)
    {
        if (string.IsNullOrEmpty(url)) return false;
        if (url.StartsWith("http://") || url.StartsWith("https://")) return false;
        if (url.StartsWith("#")) return false;  // Anchor
        if (url.StartsWith("mailto:")) return false;
        return true;
    }
}
```

## Kun määrität Markdig-putkea, lisää TOC-laajennus:

Putken sijainti:

```markdown
<fetch markdownurl="https://api.example.com/status.md"
       pollfrequency="1"
       showsummary="true" disable="true"/>
```

Toisin kuin jotkut Markdigin laajennukset, TOC-laajennus

> _Ei sillä ole väliä, mihin lisäät sen.[putkeen.](https://api.example.com/status.md)Laajennus automaattisesti:_

Lisää jäsennelmänsä jäsennyslistan alkuun (kohta 0)

```markdown
<fetch markdownurl="https://example.com/docs.md"
       pollfrequency="24"
       showsummary="true"
       summarytemplate="Last updated: {retrieved:long} | Status: {status} | Next refresh: {nextrefresh:relative}" disable="true"/>
```

Renderit ovat sittenkin valmiit, ja ne keräävät otsikoita koko asiakirjasta

> Joten voit lisätä

missä tahansa - putken kokoonpanon alussa, keskellä tai lopussa.

- `{retrieved:format}`Tärkeää:
- `{age}`TOC-laajennus on täysin riippumaton noutolaajennuksesta.
- `{url}`Ne on vain pakattu yhteen mukavuuden vuoksi.
- `{nextrefresh:format}`Voit:
- `{pollfrequency}`Käytä TOC:tä ilman noutamista
- `{status}`Käytä noutamista ilman TOC:tä

## Käytä molempia yhdessä

Huomaa:`disable="true"`TOC-merkki toimii sekä keskeisissä markown-tiedostoissasi että noudetuissa etäsisällöissäsi.

```markdown
<!-- This will be processed and fetch content -->
<fetch markdownurl="https://example.com/README.md" pollfrequency="24"/>

<!-- This will NOT be processed - useful for documentation -->
<fetch markdownurl="https://example.com/README.md" pollfrequency="24" disable="true"/>
```

Jos haet GitHubilta README:n, joka sisältää

- Se luo automaattisesti sisällysluettelon kyseisen asiakirjan otsikoista (olettaen, että olet lisännyt
- putkeen).
- Linkin muuntaminen

Kun haet etämerkintää (etenkin GitHubista), suhteelliset linkit katkeavat.`<fetch>`Laajennus voi automaattisesti kirjoittaa ne uusiksi:`<fetch-summary>`Tämä muuttaa:

```markdown
<fetch-summary url="https://example.com/api/status.md" disable="true"/>
```

## Säilyttää absoluuttiset URL-osoitteet ja ankkurit

Toteutus käyttää Markdig AST -järjestelmää linkkien kirjoittamiseen:

```csharp
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddPostgresMarkdownFetch(connectionString);

        var sp = services.BuildServiceProvider();
        var eventPublisher = sp.GetRequiredService<IMarkdownFetchEventPublisher>();

        // Subscribe to events
        eventPublisher.FetchBeginning += (sender, args) =>
        {
            Console.WriteLine($"Fetching {args.Url}...");
        };

        eventPublisher.FetchCompleted += (sender, args) =>
        {
            var source = args.WasCached ? "cache" : "remote";
            Console.WriteLine($"Fetched {args.Url} from {source} in {args.Duration.TotalMilliseconds}ms");
        };

        eventPublisher.FetchFailed += (sender, args) =>
        {
            Console.WriteLine($"Failed to fetch {args.Url}: {args.ErrorMessage}");
        };
    }
}
```

Hae metatietojen yhteenveto

```mermaid
sequenceDiagram
    participant MD as Markdown Processor
    participant EP as Event Publisher
    participant FS as Fetch Service
    participant ST as Storage Backend
    participant L as Your Listeners

    MD->>EP: FetchBeginning
    EP->>L: Notify FetchBeginning
    EP->>FS: FetchMarkdownAsync(url)
    FS->>ST: Check Cache
    alt Cache Fresh
        ST-->>FS: Cached Content
        FS->>EP: FetchCompleted (cached=true)
    else Cache Stale/Missing
        FS->>FS: HTTP GET
        alt Success
            FS->>ST: Update Cache
            ST-->>FS: OK
            FS->>EP: FetchCompleted (cached=false)
        else Failure
            FS->>EP: FetchFailed
            EP->>L: Notify FetchFailed
        end
    end
    EP->>L: Notify FetchCompleted
    EP->>L: Notify ContentUpdated
    FS-->>MD: MarkdownFetchResult

    Note over L: Listeners can be: Logging, Metrics, Telemetry, Webhooks
```

# Voit näyttää lukijoille, milloin sisältöä on viimeksi haettu:

Tämä tehdään jalankulkijan kanssa:

```mermaid
stateDiagram-v2
    [*] --> CheckCache: Fetch Request

    CheckCache --> Fresh: Cache exists & age < pollFrequency
    CheckCache --> Stale: Cache exists & age >= pollFrequency
    CheckCache --> Missing: No cache entry

    Fresh --> ReturnCached: Return cached content
    ReturnCached --> [*]

    Stale --> FetchRemote: Attempt HTTP GET
    Missing --> FetchRemote: Attempt HTTP GET

    FetchRemote --> UpdateCache: Success
    FetchRemote --> HasStale: Failure

    UpdateCache --> ReturnFresh: Return new content
    ReturnFresh --> [*]

    HasStale --> ReturnStale: Return stale cache
    HasStale --> ReturnError: No cache available

    ReturnStale --> [*]
    ReturnError --> [*]

    note right of Fresh
        pollFrequency = 0
        means always stale
    end note

    note right of HasStale
        Stale-while-revalidate
        pattern ensures uptime
    end note
```

Aines noudetaan

1. **https://api.example.com/status.md**06. tammikuuta 2025 (2 tuntia sitten)
2. **Tai muokkaa mallia:**Tuotos:
3. **Viimeksi päivitetty: 06. tammikuuta 2025 14:30 Tila: välimuistissa Seuraava päivitys: 22 tunnin kuluttua**Saatavilla olevat paikanhaltijat:
4. **- Viimeinen noutopäivä/aika**- Ihmisen luettavissa oleva aika noutamisesta lähtien

- Lähdekoodin URL**- Kun sisältö virkistyy**- Välipalan kesto tunneissa

# - Käpyjen tila (tuore/pakattu/talli)

Dokumentaatiokäsittelyn estäminen

```csharp
public class MarkdownController : Controller
{
    private readonly IMarkdownFetchService _fetchService;

    public async Task<IActionResult> InvalidateCache(string url)
    {
        var removed = await _fetchService.RemoveCachedMarkdownAsync(url);

        if (removed)
        {
            return Ok(new { message = "Cache invalidated" });
        }

        return NotFound(new { message = "No cache entry found" });
    }
}
```

Kun kirjoitat dokumenttia noutolaajennuksesta (kuten tästä artikkelista!), sinun täytyy näyttää tunnisteet ilman, että niitä käsitellään.

```csharp
// GitHub webhook notifies of README update
app.MapPost("/webhooks/github", async (
    GitHubWebhookPayload payload,
    IMarkdownFetchService fetchService) =>
{
    if (payload.Repository?.FullName == "user/repo" &&
        payload.Commits?.Any(c => c.Modified?.Contains("README.md") == true) == true)
    {
        var url = "https://raw.githubusercontent.com/user/repo/main/README.md";
        await fetchService.RemoveCachedMarkdownAsync(url);

        return Results.Ok(new { message = "Cache invalidated" });
    }

    return Results.Ok(new { message = "No action needed" });
});
```

# Käytä

Ominaisuus:

```csharp
public class MarkdownFetchServiceTests
{
    [Fact]
    public async Task FetchMarkdownAsync_CachesContent()
    {
        // Arrange
        var services = new ServiceCollection();
        services.AddLogging();
        services.AddInMemoryMarkdownFetch();
        var sp = services.BuildServiceProvider();

        var fetchService = sp.GetRequiredService<IMarkdownFetchService>();
        var url = "https://raw.githubusercontent.com/user/repo/main/README.md";

        // Act - First fetch (from network)
        var result1 = await fetchService.FetchMarkdownAsync(url, 24, 0);

        // Act - Second fetch (from cache)
        var result2 = await fetchService.FetchMarkdownAsync(url, 24, 0);

        // Assert
        Assert.True(result1.Success);
        Assert.True(result2.Success);
        Assert.Equal(result1.Content, result2.Content);
    }

    [Fact]
    public async Task FetchMarkdownAsync_ReturnsStaleOnFailure()
    {
        // Arrange
        var services = new ServiceCollection();
        services.AddLogging();
        services.AddInMemoryMarkdownFetch();
        var sp = services.BuildServiceProvider();

        var fetchService = sp.GetRequiredService<IMarkdownFetchService>();
        var url = "https://httpstat.us/200?sleep=100";

        // Act - First fetch succeeds
        var result1 = await fetchService.FetchMarkdownAsync(url, 0, 0);

        // Change URL to fail
        var badUrl = "https://httpstat.us/500";

        // Act - Second fetch fails, should return stale
        var result2 = await fetchService.FetchMarkdownAsync(badUrl, 0, 0);

        // Assert
        Assert.True(result1.Success);
        // Even though fetch failed, we return success with stale content
        Assert.True(result2.Success);
    }
}
```

# Vammainen tunniste on edelleen markdown as-is, täydellinen:

Kirjoitetaan dokumentteja itse laajennuksesta

1. **Esimerkkien luominen tutoriaaleissa**Tagien syntaksin näyttäminen laukaisematta noutoja`ConcurrentDictionary`Tämä toimii molemmille
2. **sekä**tunnisteet:
3. **Tapahtuman seurantajärjestelmä**Laajennus julkaisee tapahtumia kaikille noutotoiminnoille:
4. **Tämä helpottaa integroitumista Application Insightsiin, Prometheukseen tai hakkuuinfrastruktuuriin:**Välimuististrategia yksityiskohdissa`IHttpClientFactory`Välimuistikäyttäytyminen noudattaa valtiollisen koneen kaavaa:
5. **Tärkeimmät oivallukset tässä:**Tuoreet sämpylät

- Palaa heti, verkkoa ei osunut.

- Stale Cache
- - Yritä hakea tuoretta, mutta peräänny, jos nouto epäonnistuu
- Kadonnut välimuisti
- - Täytyy noutaa tai palauttaa virhe

# Nollamittauksen frekvenssi

- Hakeudu aina tuoreeksi (hyödyllinen testaukseen)

```yaml
name: Publish Markdig.FetchExtension

on:
  push:
    tags:
      - 'fetchextension-v*.*.*'

permissions:
  id-token: write
  contents: read

jobs:
  build-and-publish:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Setup .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '9.0.x'

    - name: Extract version from tag
      id: get_version
      run: |
        TAG=${GITHUB_REF#refs/tags/fetchextension-v}
        echo "VERSION=$TAG" >> $GITHUB_OUTPUT

    - name: Build
      run: dotnet build Mostlylucid.Markdig.FetchExtension/Mostlylucid.Markdig.FetchExtension.csproj --configuration Release -p:Version=${{ steps.get_version.outputs.VERSION }}

    - name: Pack
      run: dotnet pack Mostlylucid.Markdig.FetchExtension/Mostlylucid.Markdig.FetchExtension.csproj --configuration Release --no-build -p:PackageVersion=${{ steps.get_version.outputs.VERSION }} --output ./artifacts

    - name: Login to NuGet (OIDC)
      id: nuget_login
      uses: NuGet/login@v1
      with:
        user: 'mostlylucid'

    - name: Publish to NuGet
      run: dotnet nuget push ./artifacts/*.nupkg --api-key ${{ steps.nuget_login.outputs.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
```

Tätä kaavaa kutsutaan nimellä

# vanhentunut voimassaoloajan pidentäminen

Ja se on erinomainen luotettavuuden kannalta.

```markdown
# My NuGet Package Documentation

Here's the official README from GitHub:

<fetch markdownurl="https://raw.githubusercontent.com/scottgal/mostlylucidweb/main/Umami.Net/README.md"
       pollfrequency="24"
       transformlinks="true"
       showsummary="true"
       summarytemplate="*Fetched {age} from GitHub*" disable="true"/>

# Installation

The package is available on NuGet...
```

Vaikka lähteesi kaatuisi, sivustosi palvelee jatkuvasti välimuistissa olevaa sisältöä.

# Välipalan poisto ja johtaminen

Joskus sinun täytyy mitätöidä välimuisti manuaalisesti:

1. **Tai verkkokoukkujen kautta, kun sisältö muuttuu:**Laajennuksen testaaminen
2. **Laajennus sisältää kattavia testejä.**Rakensin ne näin:
3. **Suorituskykyä koskevia huomioita**Laajennus on suunniteltu suoritukseen:
4. **Rinnakkaissanakirja**- Muistettavat käyttötavat
5. **langan turvalliseen käyttöön**SemaforiSlim
6. **- Tiedostopohjainen käyttää async-lukitusta estääkseen kisaolosuhteet**Tietokantahakemistot

- Kaikilla tietokantatoimittajilla on asianmukaiset hakemistot välimuistin avaimissa

- [HTTP-asiakaspooli](https://www.nuget.org/packages/mostlylucid.Markdig.FetchExtension)
- [- Käytökset](https://www.nuget.org/packages/mostlylucid.Markdig.FetchExtension.Postgres)
- [Tehokkaaseen liitännän uudelleenkäyttöön](https://www.nuget.org/packages/mostlylucid.Markdig.FetchExtension.Sqlite)
- [Asynkki koko matkan](https://www.nuget.org/packages/mostlylucid.Markdig.FetchExtension.SqlServer)

- Ei estäviä puheluita, kaikki on async[Tyypilliset suoritusnumerot kotipalvelimellani:](https://github.com/scottgal/mostlylucidweb/tree/main/Mostlylucid.Markdig.FetchExtension)

Cache-osuma: < 1ms