Embedding external markdown

기여 기능
1

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?

2

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.

1개의 좋아요
3

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

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.

4

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?

1개의 좋아요
5

레비전을 GitHub에 자동으로 동기화하는 데 어떤 접근 방식을 취하시겠습니까? 혹시 생각하고 계신 방향에 대해 간단히 알려 주실 수 있을까요?

6

이 작업을 위해 discourse_api gem을 사용하겠습니다:

  1. crontab을 설정하여 원하는 토픽(및 게시물)의 변경 사항을 감시합니다.
  2. 변경 사항이 발생할 때마다 최신 버전을 Git 저장소(예: 정적 사이트)로 다운로드하고 커밋합니다. 게시물의 원본 마크다운 버전(post_id.md)을 다운로드하거나 HTML을 위한 cooked 버전을 다운로드할 수 있습니다(이 경우 Discourse 인스턴스의 프로토콜과 호스트명을 포함하도록 모든 URI가 절대 경로가 되도록 URI를 다시 작성해야 합니다).

API 문서와 gem의 examples 디렉터리가 유용합니다.

2개의 좋아요