# Incorporare markdown esterno

**URL:** https://meta.discourse.org/t/embedding-external-markdown/118601
**Category:** Feature
**Created:** [24 Maggio 2019, 11:08am UTC](https://meta.discourse.org/t/embedding-external-markdown/118601 "2019-05-24T11:08:30Z")
**Posts on this page:** 6
**Page:** 1

<div class="post-metadata">

### Author: ![hellekin](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/hellekin/32/51636_2.png) [@hellekin](https://meta.discourse.org/u/hellekin)
#### Post date: [24 Maggio 2019, 11:08am UTC](https://meta.discourse.org/t/embedding-external-markdown/118601/1 "2019-05-24T11:08:30Z")

</div>

## Use Case

1. A software project maintains its documentation in a Git repository.
2. The master version of a file is the canonical version of this documentation
3. We want to use Discourse to facilitate collaborative edition and criticism of the living document

## Approach

1. Copy the link to the raw markdown file from the Git repository, e.g., `https://git.example/org/documentation/raw/master/INSTALL.md` in the new topic title field
2. Discourse retrieves title and markdown content that becomes topic content
3. Discourse watches for changes and rebuilds HTML when needed, maintaining versions

Then the readers always have access to the latest markdown version in Git, while editors can use the power of Discourse to discuss changes.

## Down the road

When ActivityPub support is added to Discourse and Git (via ForgeFed), this type of integration can be expanded to include cross-application document synchronization, without the need to know about Git.

The first step is to “onebox” external markdown. This would as well allow to integrate with a static blog directly from it’s Git repository, consolidating the publication process (i.e., by generating topics matching static pages at publication time)

* * *

What current solutions (API calls?) exist to do this besides embedding comments on the static page? How far from embed.js would that lead us?

---

<div class="post-metadata">

### Author: ![codinghorror](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/codinghorror/32/110067_2.png) [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [25 Maggio 2019, 1:17am UTC](https://meta.discourse.org/t/embedding-external-markdown/118601/2 "2019-05-25T01:17:41Z")

</div>

Er what? Why not just have a link to it in the first post, and the discussion in the replies?

Alternately you could whitelist an `<iframe>` if you are dead set on having a live view of a remote doc.

---

<div class="post-metadata">

### Author: ![hellekin](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/hellekin/32/51636_2.png) [@hellekin](https://meta.discourse.org/u/hellekin)
#### Post date: [25 Maggio 2019, 8:12am UTC](https://meta.discourse.org/t/embedding-external-markdown/118601/3 "2019-05-25T08:12:56Z")

</div>

> [@codinghorror](#):
>
> Why not just have a link to it

You cannot que not use any other Discourse feature on a link. The idea is to integrate the content, not just link to it.

> [@codinghorror](#):
>
> you could whitelist an `<iframe>`

Why not have native markdown instead? JavaScript can do that, right?

Just thinking ahead of the ActivityPub support: if instances can already have a mechanism to relay existing content from one another, it all gets easier to follow a single topic across instances, and to generate static sites from Discourse topics.

---

<div class="post-metadata">

### Author: ![codinghorror](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/codinghorror/32/110067_2.png) [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [25 Maggio 2019, 8:40am UTC](https://meta.discourse.org/t/embedding-external-markdown/118601/4 "2019-05-25T08:40:29Z")

</div>

Why not do it the other way around? Have the first post be a wiki and _it_ is the source of truth and sync those revisions with GitHub?

---

<div class="post-metadata">

### Author: ![simonsan](https://avatars.discourse-cdn.com/v4/letter/s/e9bcb4/32.png) [@simonsan](https://meta.discourse.org/u/simonsan)
#### Post date: [15 Febbraio 2020, 5:49am UTC](https://meta.discourse.org/t/embedding-external-markdown/118601/5 "2020-02-15T05:49:12Z")

</div>

Qual sarebbe il tuo approccio per sincronizzare automaticamente le revisioni su GitHub? Potresti darmi un’idea di cosa avevi in mente, per favore?

---

<div class="post-metadata">

### Author: ![hellekin](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/hellekin/32/51636_2.png) [@hellekin](https://meta.discourse.org/u/hellekin)
#### Post date: [23 Febbraio 2020, 3:25pm UTC](https://meta.discourse.org/t/embedding-external-markdown/118601/6 "2020-02-23T15:25:42Z")

</div>

Per questo utilizzerei il [discourse\_api gem](https://github.com/discourse/discourse_api):

1. Imposta un crontab per monitorare i topic (e i post) di interesse in cerca di modifiche
2. Ogni volta che si verifica una modifica, scarica l’ultima versione in un repository Git (ad esempio, un sito statico) e effettua il commit. Puoi scaricare sia la versione Markdown originale del post (`post_id.md`) sia la versione elaborata per HTML (ma in tal caso dovresti riscrivere gli URI per assicurarti che siano tutti assoluti e includano quindi il protocollo e il nome host dell’istanza Discourse.)

La [documentazione API](https://docs.discourse.org/) è utile, così come la directory `examples` nel gem.