iilab/contentascode

Content as Code

contentascode's Issues

Document possible legacy technology constraints and requirements

• Document synchronisation, transition and migration from Drupal
• Document synchronisation, transition and migration from Django
• Document synchronisation, transition and migration from EdX
• Document synchronisation, transition and migration from Android content strategies (document various content strategies)
• Document adoption from Jekyll static site generation pipeline
• Document adoption from Metalsmith static site generation pipeline
• Document adoption from other static site generation pipeline

Consider prosemirror

A nice markdown editor:

https://prosemirror.net/demo/collab.html#edit-Example

It also allow collaborative editing.

Then we would need to figure out, how/when to save the document collaboratively edited to git.

Implement link checker and other server side validation on Travis

Feeding into #7 implementing a server side link checker would be a good PoC. What would be even better is an isomorphic link checker.

Deal with external review workflows using office suites (ODT, DOC, DOCX).

Part of #8

This tool which maintains a Markdown representation of word docs could be a good starting point.

Choose editor(s) as a basis for the authoring environment

• Define criterias and list possible choices
• Invite contributors to comment
• Decide which are unavoidable editors
• Get started on easiest one to extend

	Markdown	Git	Inplace	Active
Prose	Yes	github	No	No
Gitbook	Yes	git	No	Yes
Dillinger	Yes	github	No
Aloha			Yes
Pen Editor	Yes	No	Yes	Yes
ContentEditable	No	No	Yes	Yes
Realms.io	Yes	Yes	Preview	Yes
Substance	No	No	Preview	Yes
PubPub	Yes	?	Preview	Yes
VisualEditor	No	?	Yes	Yes

See the current analysis at http://iilab.github.io/contentascode/technology/authoring/

Write Guidelines for Markdown structure

@Coccodrillo @poser @houndbee

Here's some thoughts about the approach to exporting existing content in a "content as code"

Structure

One of the driving principles is to focus on AX (the Author's Experience). Therefore the content should be in a simple file structure that strongly reflect the organisation of the content in "its natural habitat" i.e. where it's meant to be displayed in the end. This will make it easy to find content. Here's an example of this with Open Mentoring

The content on the app here :

The file structure on prose/github is very similar:

The UX could be improved more by dealing with titles better. (Here Dealing with Emergencies is practice-1-emergencies and Getting Started is 0-getting-started).

Here's an example of how the file structure is on the Open Mentoring app:

/                           # root folder

  en/                       # top level folder for each language

    resources/              # Static or dynamic content that are not part of exchanged 
                            # content (they hold information but are not meant to be 
                            # structured like learning content)

    topics/                 # Contains Topics.

      a-topic/              
      another-topic/        # Contains Units

        a-unit/
        another-unit/       # Contains Stacks

          1-intro.md        # Example Stack.
          1-intro-hrd.md    # Example Stack for the hrd profile.
          ...

Granularity

Another important consideration is how the content is broken down. Currently in Open Mentoring the approach is to have "stacks" be Markdown files. Read more about in the openmentoring MODEL.md doc.

Multiple stacks are then aggregated into single pages on the web:

And an individual stack (here under the Scenario heading) is actually split (using <br> as the token right now) into cards on the mobile app like this:

And this is what it looks like on Prose

The source Markdown for this is here:

https://github.com/iilab/openmentoring-content/edit/master/en/topics/practice-1-emergencies/1-seeking-help/2-scenario.md

What I'd like is to maintain a AX focused approach here, but this probably means allowing authors to switch context depending on what they want to look at (web view, mobile view,...). Right now there's a trade off in Open Mentoring in order to make it easy

Open Questions

Currently the openmentoring-curation layer also allows to specify metadata that will be inherited by the children files, which helps DRY for instance the source metadata key in the index.md file here will be applied to all the stacks in the same folder.

Also to avoid having to add frontmatter metadata (or companion metadata files - like having a content.md with only markdown and content.json or content.yaml with only metadata) openmentoring uses keywords in file names to create metadata keys (which is also described in the MODEL.md file).

There will be cases where particular pieces of content are reused in different places in the app. My current thinking is to have these reusable components included via symlinks for content that's in a file, or some kind of block level include syntax (see middlematter discussion in #12) which could also work for including remote content.

The usability of this completely depends on building on top of a content authoring tool like prose, developing plugins to deal with middlematter, symlinks or remote includes in a way that is natural for authors.

Transclusion of blocks via fragment identifiers

If we have a document.md file with this content:

# Title 1
Content 1.A
# Title 2
## Title 2.1
Content 2.B
## Title 2.2
Content 2.C
# Title 3
Content 3.D

I would like to be able to transclude a block inside this document for instance Content 2.C by using the syntax:

:[](document.md#title-2.2)

Define v0.1.0 goals and document Roadmap and Governance

• Discuss v0.1.0 goals
• Write v0.1.0 user stories
• First draft for overall Roadmap
• First draft for decision making process

Update linked task status

#40 #43

Allow linked tasks to display an updated status on the page where they are in/trans-cluded

• Strikethrough linked task if complete at generation (depends on #42)
• Display task status live through client side transclusion widget (#44)

Notes

Here are some proposals for how to inline task info.

This is a linked task with only the task number [#45](https://github.com/iilab/contentascode/issues/45)

[This is a linked task with a whole sentence and the task number #45](https://github.com/iilab/contentascode/issues/45)

This is a linked task where the task title is transcluded :[#45 title](https://github.com/iilab/contentascode/issues/45)

Here's what it would look like when displayed on a web page if the task is completed:

This is a linked task with only the task number #45

This is a linked task with a whole sentence and the task number #45

This is a linked task where the task title is transcluded Update linked task status #45

another nice tool - Simone

You can see it in action here:
https://yunohost.org/#/help

https://github.com/Kloadut/Simone

Metadata formats

This was brought up in #25 (comment)

YAML is the default legacy choice because of Jekyll and its Ruby heritage. It makes sense to start with it to have more compatibility out of the gate but there are a lot of interesting and maybe better (to at least some people) formats out there that could be used as well as they are terse, human readable (so thanks no XML), have a resilient syntax (which makes JSON too easy to break)

Format	Link	Readability	Resilience	Adoption	Other
YAML		++	-	+++
ArchieML	archieml.org	=	++	+
TOML	https://github.com/toml-lang/toml	+		-	Unstable
CSON	https://github.com/bevry/cson	+	-	-
MSON	https://github.com/apiaryio/mson	++	?	?

Transclusion widget

In order to manage the live display for clients of dependency status, notifications and so on (as show in the publication section on the right in the diagram below) we need a client side widget.

Implement translation workflow scripts

• Reimplement panicbutton transifex push script in Python
• Finalise push process (including stowing away non translatable json values)
• Implement pull process
• Deploy txgh server connected to this repo.
• Write roadmap for enforcing "API" changes to translation glue code (for instance deal with
• Iterate on design with a Developer Experience focus.
• Document pathways to adopt translation workflow
• Look into supporting alternate translation backends

@naturalshine

Implement github issues as a page discussion feature

There's a use case where specific pages on a site are discussed in specific github issues and could play the role of a type of forum as mentioned in #7.

Track progress of Bridge

From #2

Just met @edbice and @caiosba from meedan and they mentioned bridge https://meedan.com/en/bridge/ and the aim to provide translation collaboration features. Do you know when it will be open sourced?

This ticket is to keep track of potential open source alternatives to transifex and specifically Bridge from meedan!

Prototype implementation

Prototype should allow to do demos and showcase how key functionalities will work and improve existing content workflows.

Authoring

• Auto date plugin for content editor
• Content category/navigation plugin for content editor

Localisation

• Integrated Transifex Workflow

Management

• Gitlab Kanban Leanlabs

CMS Parity

• Comments - Isso
• Search - jekyll-search

Interoperability

• Gollum (for github and gitlab wikis)
• Gitbook - Open Mentoring
• Android - Panic Button

Streamlined

• Travis based deployment

Transclusion - Block level metadata in Markdown - i.e. middlematter

Especially in content reuse scenarios, keeping metadata (in particular Provenance metadata) is key to keep track of upstream changes in complex aggregated content pipelines.

In addition to (awesome) approaches such as @elationfoundation which generates JSON-LD from Jekyll Frontmatter documents we will surely need to manage metadata for more granular blocks of content for instance in scenarios where larger documents are made of smaller parts.

There is a scenario where the content editor aggregates smaller files with their metadata each, but it seems to break the model of having Markdown fit the view/perspective of the Author rather than bending to technical requirements.

From a usability standpoint, the ability to add "chapters" or "sections" in this way without creating folders, subfolders and small files is important to consider.

When I think about this it seems to lead to the possibility to add block level metadata in markdown. Given that adding metadata at the top is a well adopted practice across static website generators and called a frontmatter, the idea to add metadata in the middle, instead of the front called therefore be called middlematter.

I'm thinking for instance of this type of syntax (with YAML single line maps) :

1.

# An H1 without metadata
## An H2 level block with metadata --- {creator: 'seamus', source: 'elationfoundation/using-tor-browser-bundle'}

or

2.

# An H1 without metadata
## An H2 level block with metadata 
--- {creator: 'seamus', source: 'elationfoundation/using-tor-browser-bundle'}

or

3.

# An H1 without metadata
## An H2 level block with metadata 

---
creator: 'seamus'
source: 'elationfoundation/using-tor-browser-bundle'

---

I prefer 2. because it looks like a byline.

A content editor (#5) should probably hide inline block level metadata (the way prose hides document level metadata), and allow to surface them when needed.

Integration with kanban.leanlabs.io

Next version of the roadmap

The roadmap is currently based on milestones in Github and also published on the website

But there is work needed to:

• Update the current status of issues / milestones
• Think through how to reorganise the roadmap
• Publish new version of the roadmap

Iterate on the ecosystem design document

Iterate on the ecosystem design approach described at http://iilab.github.io/contentascode/approach/ and develop some non-technical introduction document to the benefits and features of such an approach. (An example of this is to enable workflows where open contribution to a website is easy and works with translation workflows).

• Setup reference implementation of the workflow on this repo (i.e. eat your own dog food or release very early)
• Migrate wiki to markdown files on this repo.
• Add structure to the content and add inputs from partnership discussions.
• Summarise possible roadmap and functional evolution stages synthetically and visually

Prose component

Possible aspects of Prose integration which are relevant to contentascode are:

• Integrate with Gitlab backend
• Easier "Fork and Pull Request" workflow for non techies. Including prose/prose#643
• Other storage location for images #5 (comment)
• Metadata first document creation (allow to input metadata - title/date/status - before opening or saving a doc.
• Transclusion support (iilab/prose#1)
• Prosemirror integration #5 (comment)
• Content "Integration" tests #11 (perhaps with isomorphic tests ran by prosemirror in the client)
• Allow offline workflow prose/prose#690
• Persist local edits to localstorage.

@dereklieu

UPDATE: Shuffled things around and added some links.

Notifications

See http://iilab.github.io/contentascode/technology/workflow/#notifications
Related to #43

Some of the use cases for this would be:

• I browse, see an interesting page and want to be notified when content on a particular page changes.
• There are "area of interests" on the site which I can join.
• Allow users to watch a particular page
• Allow users to watch an issue

Areas of interest could be mapped to a folder or subrepo if they are clearly mapped to the site content structure, or could be mapped to grouping of issues if they have their own logic (like project management, or a categorisation that's somewhat orthogonal from content):

• Allow users to watch a section (folder or subrepo)
• Allow users to watch a grouping of issues (tags, milestone,...)

UPDATE: Moving notes to the issue tracker integration issue #40

Experiment with collaborative workflows

There are a number of issues #21 #28 #40 #41 #35 #36 #37 #38 which point to various aspects of collaborative workflows.

This issue will keep track of aspects which relate to organising the Content as Code collaboration using Content as Code approaches, in the same way that the Content as Code website is an implementation of the Content as Code approach (currently with the Docsmith implementation - itself lagging a bit behind the experiments going on in the Open Integrity framework site)

Some of this is being described and developed on this page http://iilab.github.io/contentascode/technology/workflow/

another implementation of contentascode

https://github.com/daktary-team/daktary

Gollum Integration

Would allow a Gollum wiki to be a data source/sink. It would offer support for Github/Gitlab and Realms.io wikis.

• Frontmatter and other (block level) Metadata would be added and removed using 3 way diff approaches.
• Dealing with reorganisation of wiki pages into folder structures in contentascode would be a good difficult case.
• Dealing with importing content snippets from external source would be another interesting case.

Line based content review

• Could be piggy backing on Github/Gitlab's line based code review tools.
• Could be made a specific case of section level content review #38

Document possible translation workflows

Add AnchorJS

It will make things nicer and more up to date with current practices. Relates to #7

Integration with Waffle

Content Packages

Software libraries and projects both have:

• a collaborative lifecycle using git, where contributions are progressively integrated in a common repository
• a release lifecycle where a repo at a particular moment is made available to a community, usually with a version number possibly on a package repository.

It seems to make sense to also think about packaging content units when they are part of the same release cycle, and would benefit from being tagged with a version number, for instance to update clients that use the content package. This seems that it would be a building block of a technical approach to content reuse, where content packages would be collaboratively maintained and reusable.

I think there's a lot to learn from OFK's Data Packages which recently hit 1.0.

I've done some basic implementation piggy backing on the npm registry for safetag with:

• A docsmith feature which automates npm to download the latest package.
• A content.yml description which contains content package dependencies for a particular project.
• A first content package which contains its content and its instructions for it to be built, published on the npm registry.

Some open questions and directions of work are:

• Wrapping up the package release in a high level interface.
• Think about light-weight forkability and three way merge in the context of packages.
• Transclusion between content packages.
• Look into how this fits with content reuse

Discuss metadata needs

@elationfoundation

Following on our discussion and your great research work in this draft, I thought I'd take down some notes to continue the conversation in the open. By the way DocOps is a really cool moniker for this approach too :)

If we abstract away from particular implementation then one of the most important needs to allow some form of interoperability is to agree on metadata (or at least map metadata format to one another). There are possibly some data format considerations (for instance with #12) for interop at the implementation level but let's set them aside for now.

If we look at it from a use case perspective (looking through the metadata available here https://raw.githubusercontent.com/elationfoundation/using-tor-browser-bundle/master/metadata.md) then

• in terms of basic publishing, there's convergence generally on DC as a minimal set of metadata for any document (basically creator and title). It's a low hanging fruit if our Jekyll boilerplate (#15) generates DC in JSON-LD.
• in a software documentation context, there is an added need to refer to the software in question in a unique way. This is not a trivial matter as mentioned here and here. There's also aspect related to the availability of software or content for specific platforms. There's also an interesting use case of displaying citation of code from github described here: https://guides.github.com/activities/citable-code/
• in an online education context, there's a need for specifying which types of educational material a particular piece of content refers to (background information, quizz, reference material, activity,...). Domain specific ontologies regarding education will help (for instance grounding this in the ADIDS model or other models).

I can think of other needs that could be included as metadata such as:

• Intended Audiences, in terms of
  • Geography (including language or communities - possibly virtual)
  • Profession
  • Other aspects useful in an educational context (learning style, proficiency in related matter,...) particularly if adaptive learning is a part of it.
• Intention, i.e. if the user comes with a particular intention then is the content relevant?

With other domain specific concerns (for instance with digital security education) other aspects will come up such as risk profiles or threats.

Django Integration

Dealing with migration in and out of Django would probably start with a simple case, looking at a model with a single table being identified as content, published through a REST API with a JSON format and rendered/parsed to markdown.

On the Django side the framework could be http://www.django-rest-framework.org/ allowing to GET/PUT/POST JSON objects first and maybe implement later renderers and parsers for our Markdown Data enabled flavor.

Export

Export from Django would be done by making JSON objects (or arrays of JSON objects) available through an REST interface.

The creation of Markdown files would probably be using a similar approach of templated Markdown as here.

Block level metadata would be automatically constructed (using for instance JS dot notation by introspecting the template).

A JSON schema file would be produced to be used for both client/server side validation

Import

The Markdown would be parsed as JSON and validated with the JSON Schema on the client and/or through a integration/build script (Travis for instance) before being submitted to the REST API.

Todo

• Implement single object/table case.
• Implement single object/table with linked object/tables as tags or categories.
• Based on the experience with the 2 previous steps, design a system for the more general case (probably starting with a simple case such as blog post / author profile)
• Design for the more general case (including allowing template logic - ifs and loops for instance - and reconstructing objects updates from it).

Related to #4

Implement Proof of concept

Needed features for a proof of concept implementation. Existing reference implementation is on this repo https://github.com/iilab/contentascode

Workflow Integration

Authoring

• Github
• Jekyll
• Prose
• Some sort of client side validation and CI setup

Translation

• Transifex

Collaboration

• Github - Fork and pull request
• Travis CI message

Management

• Waffle

Channels

• Web
• Book

Technology

CMS Parity

• Comments - Github issues?
• Stats - Piwik

Deployment

• Documented installation
• Single repo and one click deploy

Discussing user feedback mechanisms

I just came across the Web Annotation Architecture Document produced by the W3C Web Annotation group. I think that it lays out a very clear technological implementation for user-comments/annotations. I think that it would be a good idea to see if they have existing or upcoming implementations to extend/use.

Code review integration

This is an issue meant to keep track of various sub issues that relate to integration with code review tools as a user interaction mechanism (#28)

• Line based content review #37
• Section based content review #38 might also be connected (although we might be able to deal with it simply by considering paragraphs as single lines, which should work for some time).

Section level content review

Such as with Carnival app carnivalapp.io

One click deploy

The idea is to allow a fast deployment workflow of content as code site in the Deploy to Heroku button way. I can't remember where I saw a very impressive list of options to deploy a tool but it also had GCE, Digital Ocean and maybe Sandstorm. #7

Allow transclusion of API endpoint results

This could be an underlying facility for #40 or #41 where the source of a page could describe an API endpoint (ideally serving a JSON object) and some form of templating to display data.

For instance:

• have a /issues/index.md page with:

---
source: https://github.com/api/blahblah
layout: issues

---

• have a /layouts/issues.jade file such as

each issue in issues
  li= issue.name
    a(href=issue.link) issue.description

This should be fairly easy with Metalsmith and the metadata plugin after an API fetch to file step, or by creating a plugin that directly consumes the API at each generation run (which could be based on the contentful or primsic metalsmith plugins which do this).

• then the issue list could be transcluded from a page with :[](/issues)
• then an individual issue could be transcluded with the awesome syntax :[](/issues#2) (related to #32 for transclusion of fragment blocks)

Minimum viable implementation

Needed features for a minimum viable implementation which would allow partners to adopt the workflow and technology in production.

Authoring

• Gitlab backend
• Preview in Context

Collaboration

• Seamless "Make a copy" and "Contribute my changes" features.

Management

• Manage drafts
• Manage editing workflow stages
• Manage external review stages (ODT track changes?)
• 3 way diffs to maintain content variations (OS variations for tool guides)

Reuse

• Personal media library
• Project media library
• Link management and broken link detection

CMS Parity

• Comments
• Stats
• Search
• Recently updated - Most viewed - Recently commented on

Flexible Structure

• Invisible Metadata Blocs in Content Authoring environment.
• Round-trip synchronisation implementation with CMSes (Drupal, Django)

Streamlined

• Unified User Interface

Integrate Cryptocat example as collaboration and tracking use case

As mentioned in this issue iilab/openmentoring-web#2 by @elationfoundation

When I added a similar issue for SAFETAG I decided to do my civic duty and searched all markdown files on github for cryptocat and added issues to any guides I found. One of the many benefits/problems to having low barriers to collaboration

And here it is in pictures from https://github.com/elationfoundation :

And here's how it looks like on our side when responding to the issue on iilab/openmentoring-web#2 (reference):

This is an awesome example of how collaboration looks like with a content as code approach.

Design DX for contentascode adoption

Part of #7

My thoughts on this would be to focus on allowing user to start from a project scaffold:

• a Blog (Jekyll compatible) with added "Contribute to this page" links.
• a Wiki (Gollum compatible)
• a Resource website
• a Software documentation site

We could create repos (contentascode-blog, contentascode-wiki, contentascode-website, contentascode-doc) that are ready to clone with some sensible defaults.

The default pipelines would have a travis.yml that push to a gh-pages branch.

We could also look into Grunt-init or Yeoman Project Scaffolding tools to allow configuration of various options such as:

• Choice of templating language and other frontend framework choices
• Choice of integration backend (Jekyll/Metalsmith/...)
• Choice of a theme (Bootstrap and variants, Foundation, GH Pages themes...)
• Adoption of metadata schemas (SPAR, Provenance, DigiSec Taxonomy).
• Configuration of tools like Prose with good usable defaults.
• Enabling of other CI backends (Gitlab CI, Jenkins, Thoughtworks Go,...)
• Configuration, integration and deployment (Heroku button style) of micro-services (like commenting, stats,...)

We also need to think about migration and various options to use integrations to facilitate a progressive transition process.

Reference Implementation Matrix

Name	Description	Repo	Editor	Generator	Build	Hosting	Services
scaffold-github-pages	Fork and play.	Github	Prose	Jekyll	Github Pages	Github
scaffold-github-jekyll-travis	With Jekyll and Travis CI	Github	Prose	Jekyll	Travis	Github
scaffold-github-metalsmith-travis	With Metalsmith and Travis CI	Github	Prose	Metalsmith	Travis	Github
scaffold-jekyll-jenkins	Open souce stack	Gitlab	Hosted Prose	Jekyll	Jenkins	Self-Hosted
scaffold-metalsmith-gitlabci	Open souce stack with metalsmith	Gitlab	Hosted Prose	Jekyll	Gitlab CI	Self-Hosted
infra-heroku	Push to deploy micro-service infra	Gitlab	Hosted Prose	Jekyll	Jenkins	Heroku	Single container
infra-docker	Docker single server micro-service infra						Multi-container
infra-ansible	Distributed micro-service infra						Multi-server

Migrate to scaffold-github-jekyll-travis

Related to #15

This repo is currently an implementation of the stack-github-pages approach. Not sure it can be made completely fork and play as it might always require to activate Pages on the github repo.

Moving to the stack-github-jekyll-travis approach will add the following features:

• Build/CI process! Server side integration tests link link checking #11
• Notifications of Build success and failure on Pull Requests
• Build badges

From a DX standpoint, moving to this stack should be as simple as changing branches and merging (and configuring travis). Will open a new issue to track this.

Merges and other difficult concepts

Despite trying to create a smaller language for version control than git, some abstractions will need to be exposed especially when dealing with conflicts and merges.

If the UI would expose choices based on graphical representation like here https://developer.atlassian.com/blog/2014/12/pull-request-merge-strategies-the-great-debate/

It might make these concepts easier to grasp.

There's a need to look at the range of main and corner cases such as:

• save (commit+push)
• save as (fork+commit+push)
• contribute (fork+commit+push+pull request)
• conflict (failed push+merge+push)
  • ?

hackmd

A really nice tool:
https://github.com/hackmdio/hackmd

Here is the issue about git support: hackmdio/codimd#114

Mkdocs

Check out http://www.mkdocs.org/

Would be nice to:
content use mkdocs -> installs mkdocs (plugging in other components of the pipeline), converts what can be converted of the current generator to the mkdoc config.
content build-> uses mkdocs build in the background.

Content Reuse

The advice from @alnermcgunn on this is that there are many dimension to content that are as many obstacles to reuse:

• Editorial Style
• Format (mobile, web, print)
• Audiences
• Purpose (informational, educational,...)
• Granularity (course/lesson, how-to, tool,...)

Other obstacles would be making the packaging, "client" use and upstream contribution workflows seamless.

Finding an practical example of a content package that could be a good candidate for reuse would be a good first step to explore this idea. Maybe a module on "Using PGP"...

Design 3 way diff/merge approach for upstream changes

Part of #8

The typical use case is:

• I re-use content from an upstream provider (typically as a starting point for content adaptation)
• I modify the content.
• Upstream makes changes

The problem

• How do I integrate these changes in my adapted content?

Possible solutions (from how the code people do it)

• 3 way merges?
• recursive or weave merges?

Test

• Use openmentoring DFAK or SIAB upstream content as a test.

The upshot?

• There's already 3 way diff/merge tooling for Markdown that we can reuse.
  • https://github.com/netj/markdown-diff
  • https://github.com/adamarthurryan/dubdiff
• There's huge ecosystem of tools and practices of dealing with this problem in code that can be applied to content.
• There's innovation that could be adapted to (for instance with semantic merge)

Other interesting approaches might include using the markdown structure as the underlying data and use other diffing tools for this.

Interestingly, I couldn't find research literature about applying these tools to natural language text...

Issue tracker integration

This is an issue meant to keep track of various sub issues that relate to integration with issue trackers as a user interaction and feedback mechanism (#28)

• Listing issues associated to a project #42
• Mapping one issue to a page as a discussion feature #24
  • With #42 this could be the transclusion of an issue thread in the section of a page. Possibly adding a form which would submit to a microservice API gateway for posting to the issue tracker.
• Making the content of the issue the master content (this approach is used when the OP is refined with the inputs from the discussion thread).

Notes

Semantics

• Watch/Subscribe
  • Item
  • Group
• Participate/Mentions
• Configure Delivery
  • Channels
    • Email
    • RSS
    • IRC/Chat
    • Third party platform (Github/Gitlab/...)
  • Frequency
    • Immediately
    • Batch

The first step is to depend on an external service for notifications (despite the need to register/login). Good candidates are the Github/Gitlab issue trackers (Gitlab self-hosted allowing to avoid third party authentication dependencies).

In that case there should be mappings of content items to issues (#24) and notifications can be managed through the issue subscription mechanism. Here are possible approaches:

Approach A

Example for one master repo

Repo: https://github.com/iilab/contentascode
Issues: https://github.com/iilab/contentascode/issues

One issue could be mapped to one page.

• PROS: The issue can be used as a discussion page.
• CONS: Lots of issues.

Implementation:

• At first an issue metadata key could be added with the issue number.
• Later an issue could be created automatically via the issue tracker's API.
• Commits could be checked and amended with the proper issue number so that they appear in the issue thread.

Approach B

One master repo, issues are orthogonal to the content (a more classical setup between code and issue tracking or documentation and issues)

Repo: https://github.com/iilab/openmentoring-mobile
Issues: https://github.com/iilab/openmentoring-mobile/issues

Approach C

Multiple subrepos, corresponding to "areas of interest"

Repo: https://code.iilab.org/openintegrity/openintegrity.org
Subrepos:

• https://code.iilab.org/openintegrity/framework
• https://code.iilab.org/openintegrity/design
• https://code.iilab.org/openintegrity/practices
• https://code.iilab.org/openintegrity/impact

Piwik integration

The idea is that a statistics microservice would be able to be queried by the static website pipeline and that the results could be used to for instance order post by most viewed. #7

Allow smart linking for multi-source projects

When a project contains several subrepos (like the contentascode spike developed for the open integrity project) it would be good to allow linking across parent repo and subrepo in a way that is simple for instance

• [Link in the parent repo to a sub folder in the parent repo](/subfolder/file.md)
• [Link in the parent repo to a subrepo](/subrepo_a/folder/file.md) -> We need to manage subfolder/subrepo name collisions (via the pre-commit validation run? #11)
• [Link from a subrepo to the parent repo](/subfolder/file.md)
• [Link from a subrepo to another subrepo](/subrepo_b/file.md)

With the baseurl problem (when sites are served from scheme://host/folder/) this needs some kind of pre-processing.