├── .gitignore ├── .ruby-version ├── .travis.yml ├── 404.html ├── Gemfile ├── Gemfile.lock ├── LICENSE ├── README.md ├── _config.yml ├── _content.yml ├── _includes ├── head.html └── sidebar.html ├── _layouts ├── default.html ├── page.html └── post.html ├── _posts ├── 2012-02-06-whats-jekyll.md ├── 2012-02-07-example-content.md ├── 2013-12-28-introducing-hyde.md └── 2016-07-29-metalsmith-part1.md ├── approach.md ├── atom.xml ├── images ├── dependencies.png └── icon.svg ├── index.md ├── package.json ├── partners.md ├── public ├── apple-touch-icon-144-precomposed.png ├── css │ ├── hyde.css │ ├── poole.css │ └── syntax.css └── favicon.ico ├── status.md ├── technology.md └── technology ├── applications.md ├── architecture.png ├── authoring.md ├── existing.md ├── foundations ├── git.md ├── github.md ├── gitlab.md ├── markdown.md └── prose.md ├── implementation.md ├── implementation └── docsmith.md ├── inspiration.md ├── taxonomies.md ├── translation.md └── workflow.md /.gitignore: -------------------------------------------------------------------------------- 1 | secrets.sh 2 | _site 3 | node_modules 4 | contentascode 5 | NOTES.md -------------------------------------------------------------------------------- /.ruby-version: -------------------------------------------------------------------------------- 1 | ruby-2.2.1 2 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | sudo: false 3 | node_js: 4 | - '4.2' 5 | branches: 6 | except: 7 | - gh-pages 8 | cache: 9 | bundler: true 10 | directories: 11 | - node_modules 12 | - $HOME/.rvm 13 | - $HOME/.nvm 14 | install: 15 | - npm i pm2 http-server contentascode/broken-link-checker -g 16 | - "rvm install $(sed 's/ruby-//g' .ruby-version)" 17 | - bundle install 18 | deploy: 19 | skip_cleanup: true 20 | provider: script 21 | script: npm run deploy 22 | env: 23 | global: 24 | - GH_USERNAME=jmatsushita 25 | - CONFIG_OWNER=iilab 26 | - CONFIG_REPO=contentascode 27 | - secure: > 28 | "n4Yb8tQikDFtdNNUhEaQevdprHrU2dpFdjOuj6HxcRkwFHVJ/8IU0eyL5iUg3hnCB+kuolZYoCRCh8Z9DouErhiq7oBHRSjZ7jCHuMUK6ZSOuXBoYW4xEeEV3/K741m0n4GbEeA72JHNmY710ctkCscNJdFGIl6YbLVmis8dmON5sHjuZwKntyAt4c+2R1iHK1odkSXB9Ua/m/rZp1CX/LzVpYY7zQCdzjdcNM1OjeHqUboxu+uln03vUBaS2WRF66r/gCFi42B+Gc0U/z80whm9lVy/wszN6WTX4pUD0x564kHH5yBJQUS3vdDCgnTB55EU+lKJgJGgp70sSWJRtj+WT+uRLtR769jbnxJvwwQMHmk6GZ5Jw+YzPSYu6L8RjbgYiLnKTxOFf+tjdqeOVW5qf9JzXZtATQ0au/UoBm/ruk08D9Ok2HCkvcUWLXnTL1neMITv4Yu9x/lxim83DSByPt6+5c/X9JqSqMF8CFa7ZoHxmNbY/Ww3XHdVKFg3ksh8/ZqN9mMmxBI1PA8Kyvx5/Ci9WLWSxEozgqbnlF1jAAdOuZCxriEOUmQu3mODgMW53V+vq6QlCEWBanRFySe56MMMGXsFtctyVVFV3+i7HhpO4IvIC5soWCVYjLVR+Tv2ewMY7Wvlg0Cu+tLvjYQtD1TrcW5gt3fKylaMKiQ=" 29 | -------------------------------------------------------------------------------- /404.html: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: "404: Page not found" 4 | permalink: 404.html 5 | --- 6 | 7 |
Sorry, we've misplaced that URL or it's pointing to something that doesn't exist. Head back home to try finding it again.
8 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | gem "github-pages" -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | RedCloth (4.2.9) 5 | activesupport (4.2.5.1) 6 | i18n (~> 0.7) 7 | json (~> 1.7, >= 1.7.7) 8 | minitest (~> 5.1) 9 | thread_safe (~> 0.3, >= 0.3.4) 10 | tzinfo (~> 1.1) 11 | addressable (2.3.8) 12 | coffee-script (2.4.1) 13 | coffee-script-source 14 | execjs 15 | coffee-script-source (1.10.0) 16 | colorator (0.1) 17 | ethon (0.8.1) 18 | ffi (>= 1.3.0) 19 | execjs (2.6.0) 20 | faraday (0.9.2) 21 | multipart-post (>= 1.2, < 3) 22 | ffi (1.9.10) 23 | gemoji (2.1.0) 24 | github-pages (48) 25 | RedCloth (= 4.2.9) 26 | github-pages-health-check (= 0.6.1) 27 | jekyll (= 3.0.3) 28 | jekyll-coffeescript (= 1.0.1) 29 | jekyll-feed (= 0.3.1) 30 | jekyll-gist (= 1.4.0) 31 | jekyll-mentions (= 1.0.0) 32 | jekyll-paginate (= 1.1.0) 33 | jekyll-redirect-from (= 0.9.1) 34 | jekyll-sass-converter (= 1.3.0) 35 | jekyll-seo-tag (= 1.0.0) 36 | jekyll-sitemap (= 0.10.0) 37 | jekyll-textile-converter (= 0.1.0) 38 | jemoji (= 0.5.1) 39 | kramdown (= 1.9.0) 40 | liquid (= 3.0.6) 41 | mercenary (~> 0.3) 42 | rdiscount (= 2.1.8) 43 | redcarpet (= 3.3.3) 44 | rouge (= 1.10.1) 45 | terminal-table (~> 1.4) 46 | github-pages-health-check (0.6.1) 47 | addressable (~> 2.3) 48 | net-dns (~> 0.8) 49 | public_suffix (~> 1.4) 50 | typhoeus (~> 0.7) 51 | html-pipeline (2.3.0) 52 | activesupport (>= 2, < 5) 53 | nokogiri (>= 1.4) 54 | i18n (0.7.0) 55 | jekyll (3.0.3) 56 | colorator (~> 0.1) 57 | jekyll-sass-converter (~> 1.0) 58 | jekyll-watch (~> 1.1) 59 | kramdown (~> 1.3) 60 | liquid (~> 3.0) 61 | mercenary (~> 0.3.3) 62 | rouge (~> 1.7) 63 | safe_yaml (~> 1.0) 64 | jekyll-coffeescript (1.0.1) 65 | coffee-script (~> 2.2) 66 | jekyll-feed (0.3.1) 67 | jekyll-gist (1.4.0) 68 | octokit (~> 4.2) 69 | jekyll-mentions (1.0.0) 70 | html-pipeline (~> 2.2) 71 | jekyll (~> 3.0) 72 | jekyll-paginate (1.1.0) 73 | jekyll-redirect-from (0.9.1) 74 | jekyll (>= 2.0) 75 | jekyll-sass-converter (1.3.0) 76 | sass (~> 3.2) 77 | jekyll-seo-tag (1.0.0) 78 | jekyll (>= 2.0) 79 | jekyll-sitemap (0.10.0) 80 | jekyll-textile-converter (0.1.0) 81 | RedCloth (~> 4.0) 82 | jekyll-watch (1.3.1) 83 | listen (~> 3.0) 84 | jemoji (0.5.1) 85 | gemoji (~> 2.0) 86 | html-pipeline (~> 2.2) 87 | jekyll (>= 2.0) 88 | json (1.8.3) 89 | kramdown (1.9.0) 90 | liquid (3.0.6) 91 | listen (3.0.6) 92 | rb-fsevent (>= 0.9.3) 93 | rb-inotify (>= 0.9.7) 94 | mercenary (0.3.5) 95 | mini_portile2 (2.0.0) 96 | minitest (5.8.4) 97 | multipart-post (2.0.0) 98 | net-dns (0.8.0) 99 | nokogiri (1.6.7.2) 100 | mini_portile2 (~> 2.0.0.rc2) 101 | octokit (4.2.0) 102 | sawyer (~> 0.6.0, >= 0.5.3) 103 | public_suffix (1.5.3) 104 | rb-fsevent (0.9.7) 105 | rb-inotify (0.9.7) 106 | ffi (>= 0.5.0) 107 | rdiscount (2.1.8) 108 | redcarpet (3.3.3) 109 | rouge (1.10.1) 110 | safe_yaml (1.0.4) 111 | sass (3.4.21) 112 | sawyer (0.6.0) 113 | addressable (~> 2.3.5) 114 | faraday (~> 0.8, < 0.10) 115 | terminal-table (1.5.2) 116 | thread_safe (0.3.5) 117 | typhoeus (0.8.0) 118 | ethon (>= 0.8.0) 119 | tzinfo (1.2.2) 120 | thread_safe (~> 0.1) 121 | 122 | PLATFORMS 123 | ruby 124 | 125 | DEPENDENCIES 126 | github-pages 127 | 128 | BUNDLED WITH 129 | 1.10.6 130 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc.Name | 104 |Upvotes | 105 |Downvotes | 106 |
---|---|---|
Totals | 111 |21 | 112 |23 | 113 |
Alice | 118 |10 | 119 |11 | 120 |
Bob | 123 |4 | 124 |3 | 125 |
Charlie | 128 |7 | 129 |9 | 130 |
An interesting post about how it's going to be different this time around. I'm going write a lot more nowadays and use this blog to improve my writing.
28 | ``` 29 | ---------- 30 | To then structure the file, Metalsmith-layouts plugin parses the HTML tagged content into a layout template defined in the source file’s frontmatter. 31 | 32 | * An example of a template file. 33 | ``` 34 | 35 | 36 |An interesting post about how it's going to be different this time around. I'm going write a lot more nowadays and use this blog to improve my writing.
71 | 72 | 73 | ``` 74 | ---------- 75 | Metalsmith-markdown and Metalsmith-layouts is all that is required to render a basic static webpage. However, there are many more plugins to choose from to add functionality. Next, I walk through three additional plugins, metalsmith-permalinks, metalsmith-drafts, and metalsmith-debug. 76 | 77 | To structure a permalink, a formatted file path, metalsmith-permalinks plugin transforms file names with a pattern. A key/value pair provides the pattern parameters. Plugin objects and their parameters are invoked in the main Metalsmith configuration file, metalsmith.json. 78 | ``` 79 | "metalsmith-permalinks": { 80 | "pattern": ":title" 81 | } 82 | ``` 83 | In this example, Metalsmith-permalinks generates a permalink based on the title provided in the frontmatter. 84 | 85 | * Relevant frontmatter. 86 | ``` 87 | title: First Post 88 | ``` 89 | * The generated permalink. 90 | ``` 91 | first_post/index.html 92 | ``` 93 | ---------- 94 | The ability to create draft pages is an important tool in managing website content. It allows for content creation and page publication to be controlled separately. Metalsmith-drafts plugin looks to see if the source file is earmarked as a draft. 95 | 96 | ``` 97 | draft: true 98 | ``` 99 | If this is the case, Metalsmith does not generate a static html file. 100 | 101 | ---------- 102 | Logging tools are essential to understanding and debugging code. Metalsmith-debug plugin enables processing and compiling logs. To view the most recent log file enter into the terminal window. 103 | ``` 104 | DEBUG=* metalsmith 105 | ``` 106 | ---------- 107 | 108 | Because plugins are separate components, a good mechanism for managing and invoking them is vital. This is the job of the metalsmith.json configuration file. It contains all necessary plugin parameters in one plugin object. 109 | 110 | ``` 111 | { 112 | "source": "./_posts", 113 | "destination": "./_site", 114 | "metadata": { 115 | "title": "My Jekyll-Powered Blog", 116 | "description": "My second, super-cool, Jekyll-powered blog." 117 | }, 118 | "plugins": { 119 | "metalsmith-markdown": {}, 120 | "metalsmith-drafts": true, 121 | "metalsmith-permalinks": { 122 | "pattern": ":title" 123 | }, 124 | 125 | "metalsmith-layouts": { 126 | "engine": "swig", 127 | "directory": "_layouts" 128 | }, 129 | "metalsmith-debug": {} 130 | } 131 | } 132 | ``` 133 | The small file also contains metadata, including the locations of source and destination directories. 134 | 135 | In summary, Metalsmith is comprised of separate single function plugins managed by one configuration file. Rather than the default extensive and interdependent functionality of a CMS program, Metalsmith’s modular components and lean programming enables better control of the page creation process which in turn promotes site ownership. Metalsmith and Static Web Generators are just one tool in the post-CMS goal of content prioritization. I encourage you to read further about Static Website Generators and explore some additional tools such as Git version control and web-based content editors. 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | -------------------------------------------------------------------------------- /approach.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: page 3 | title: Approach 4 | --- 5 | 6 | > [Contribute your ideas and discuss the approach of Content as Code](https://github.com/iilab/contentascode/issues/1) 7 | 8 | * TOC 9 | {:toc} 10 | 11 | 12 | ## Design Goals 13 | 14 | These goals articulate our user-centric focus applied to the author/editor/translator/publisher experiences. 15 | 16 | ### Focused Writing 17 | 18 | > The ability for authors to focus on their content and not have to think about the technology is a design goal. 19 | 20 | The tools should disappear (literally with distraction free modes, or when using tools that are so familiar to us that we don't pay attention to them anymore - like the keyboard, or... Word). 21 | 22 | Being able to let authors use the tools that allow them to be most productive and happy is a key goal of Content as Code. Allowing a diversity of tools to be used in this workflow is a design goal, but promoting and prioritising tools that are open source, modular and well designed is part of the implementation approach. 23 | 24 | Read more about the [technology approach for content authoring](../technology/authoring) 25 | 26 | ### Localisation and translation 27 | 28 | > Integrating translation and localisation deeply in the workflow and without adding complexity is a design goal. 29 | 30 | Read more about the [technology approach for translation](../technology/translation) 31 | 32 | ### Low barrier to collaboration 33 | 34 | > Allowing others to spot problems, develop new content or adapt content for new purposes is a design goal. 35 | 36 | This should include the collaborative creation, adaptation and translation of content in sprints, remotely or with other innovative approaches. 37 | 38 | ### Track changes and manage contributions 39 | 40 | > Maintain editorial coherence by making it easy to track, review and comment on changes coming from a range of sources and improving the editor's experience is a design goal. 41 | 42 | ### Content Reuse 43 | 44 | > Allowing the discovery, tracking and updating of content used from other sources is a design goal. 45 | 46 | Multimedia content, internal links or external links should be easy to navigate and include in content. 47 | 48 | ### Multiple publication channels 49 | 50 | > Publishing to the web, books, mobile apps or other channels is a design goal. 51 | 52 | # Content as Code Approach 53 | 54 | There is a problem with content management in a [Post-CMS](#what-does-post-cms-means) context. For projects which have complex editorial workflows, adopting more lightweight approaches such as static site generation is still difficult, can create friction and are lacking in functionality. 55 | 56 | Software engineering as a discipline, has been dealing with complex contribution processes requiring to create, move, merge, transform large quantities of code. This has led to the creation of tool to be able to trace the history of changes, allow very large team contributing to similar code bases and manage, reuse vast amounts of other project's code, track changes and organise review by peers, manage documentation and its obsolecence, translations of manuals and software, test problems as early as possible in order to rapidly and frequently build software artifacts that can be deployed across servers, computer and mobile devices. 57 | 58 | [](../images/dependencies.png) 59 | 60 | Applying these concepts and lessons to editorial workflows is not trivial and requires a strong focus on author experience (as well as editor and translator experience). 61 | 62 | ## FAQ 63 | 64 | ### What does Post-CMS mean? 65 | 66 | That we've been seduced and then disappointed by [CMSes](https://en.wikipedia.org/wiki/Content_management_system "Content Management Systems") which add too much complexity and therefore create problems of maintainability of content. 67 | 68 | ### Why use Markdown and not AsciiDoc/ReStructure/Textile/Wiki syntax? 69 | 70 | That's a question of taste and we'll focus on Markdown first but we'll implement other syntaxes (and focus on software libraries that can switch syntaxes) and will accept contributions that go in this direction. 71 | 72 | ### Why not use XML/JSON/YAML... as the storage format? 73 | 74 | Having a format which is has a track record for data storage seems like a natural direction to go to, however the popularity of Markdown and of formats like YAML (both used as the data format in this format, like in Jekyll and other static website generators) is based on the fact that the representation of the content/data is elegant mainly because it removes clutter/noise and it is more resilient to syntax errors (which some could see as allowing more data corruptions). 75 | 76 | With this approach the thinking is that data corruptions will be caught by a quick feedback loop to the author, or simply by hiding structured data. 77 | 78 | ### Markdown + YAML or whatever format you design to store content/data is not proven! 79 | 80 | That's not a question but ok, we understand why you're excited or worried about this. It's true that Markdown has a history of causing pains because of loose specifications but that's pretty much settled with the [CommonMark standard](http://commonmark.org/) with a wide range of [compliant implementations](https://github.com/jgm/CommonMark/wiki/List-of-CommonMark-Implementations). Also what we're proposing is to introduce block-level metadata or [```middlematter```](https://github.com/iilab/contentascode/issues/12). There is a tradition of deriving markdown and adding flavors. This has led to a ecosystem of sometimes competing approaches to do similar things (syntax for tables is a good example of this). We'll make sure to follow this tradition and generate a strong specification for our flavor. Given that the existing practice is already to mix Markdown and YAML, Markdown probably only needs to be extended very minimally in able to allow YAML to be included inline, in a way that is elegant and minimises clutter. 81 | 82 | This integration should result in 2 well defined approaches to be used as a storage format and provide equivalence to other better known formats. 83 | 84 | ### Why not create a Word plugin? 85 | 86 | Yes! There are existing plugins to manage Markdown in Word and this fits our goals to be interoperable and extensible. 87 | 88 | ### What about open formats for multimedia content 89 | 90 | Yes! We love SVG and projects like MermaidJS which are promising ways to develop graphical content which can be reused, remixed and composed. 91 | 92 | -------------------------------------------------------------------------------- /atom.xml: -------------------------------------------------------------------------------- 1 | --- 2 | layout: null 3 | --- 4 | 5 | 6 |`,
271 | * or to a parent if there are multiple elements to show.
272 | */
273 |
274 | .message {
275 | margin-bottom: 1rem;
276 | padding: 1rem;
277 | color: #717171;
278 | background-color: #f9f9f9;
279 | }
280 |
281 |
282 | /*
283 | * Container
284 | *
285 | * Center the page content.
286 | */
287 |
288 | .container {
289 | max-width: 38rem;
290 | padding-left: 1rem;
291 | padding-right: 1rem;
292 | margin-left: auto;
293 | margin-right: auto;
294 | }
295 |
296 |
297 | /*
298 | * Masthead
299 | *
300 | * Super small header above the content for site name and short description.
301 | */
302 |
303 | .masthead {
304 | padding-top: 1rem;
305 | padding-bottom: 1rem;
306 | margin-bottom: 3rem;
307 | }
308 | .masthead-title {
309 | margin-top: 0;
310 | margin-bottom: 0;
311 | color: #505050;
312 | }
313 | .masthead-title a {
314 | color: #505050;
315 | }
316 | .masthead-title small {
317 | font-size: 75%;
318 | font-weight: 400;
319 | color: #c0c0c0;
320 | letter-spacing: 0;
321 | }
322 |
323 |
324 | /*
325 | * Posts and pages
326 | *
327 | * Each post is wrapped in `.post` and is used on default and post layouts. Each
328 | * page is wrapped in `.page` and is only used on the page layout.
329 | */
330 |
331 | .page,
332 | .post {
333 | margin-bottom: 4em;
334 | }
335 |
336 | /* Blog post or page title */
337 | .page-title,
338 | .post-title,
339 | .post-title a {
340 | color: #303030;
341 | }
342 |
343 | h1.page-title, h1.post-title {
344 | margin-top: 40px;
345 | margin-bottom: 20px;
346 | }
347 |
348 | /* Meta data line below post title */
349 | .post-date {
350 | display: block;
351 | margin-top: -.5rem;
352 | margin-bottom: 1rem;
353 | color: #9a9a9a;
354 | }
355 |
356 | /* Related posts */
357 | .related {
358 | padding-top: 2rem;
359 | padding-bottom: 2rem;
360 | border-top: 1px solid #eee;
361 | }
362 | .related-posts {
363 | padding-left: 0;
364 | list-style: none;
365 | }
366 | .related-posts h3 {
367 | margin-top: 0;
368 | }
369 | .related-posts li small {
370 | font-size: 75%;
371 | color: #999;
372 | }
373 | .related-posts li a:hover {
374 | color: #268bd2;
375 | text-decoration: none;
376 | }
377 | .related-posts li a:hover small {
378 | color: inherit;
379 | }
380 |
381 |
382 | /*
383 | * Pagination
384 | *
385 | * Super lightweight (HTML-wise) blog pagination. `span`s are provide for when
386 | * there are no more previous or next posts to show.
387 | */
388 |
389 | .pagination {
390 | overflow: hidden; /* clearfix */
391 | margin-left: -1rem;
392 | margin-right: -1rem;
393 | font-family: "PT Sans", Helvetica, Arial, sans-serif;
394 | color: #ccc;
395 | text-align: center;
396 | }
397 |
398 | /* Pagination items can be `span`s or `a`s */
399 | .pagination-item {
400 | display: block;
401 | padding: 1rem;
402 | border: 1px solid #eee;
403 | }
404 | .pagination-item:first-child {
405 | margin-bottom: -1px;
406 | }
407 |
408 | /* Only provide a hover state for linked pagination items */
409 | a.pagination-item:hover {
410 | background-color: #f5f5f5;
411 | }
412 |
413 | @media (min-width: 30em) {
414 | .pagination {
415 | margin: 3rem 0;
416 | }
417 | .pagination-item {
418 | float: left;
419 | width: 50%;
420 | }
421 | .pagination-item:first-child {
422 | margin-bottom: 0;
423 | border-top-left-radius: 4px;
424 | border-bottom-left-radius: 4px;
425 | }
426 | .pagination-item:last-child {
427 | margin-left: -1px;
428 | border-top-right-radius: 4px;
429 | border-bottom-right-radius: 4px;
430 | }
431 | }
432 |
--------------------------------------------------------------------------------
/public/css/syntax.css:
--------------------------------------------------------------------------------
1 | .highlight .hll { background-color: #ffc; }
2 | .highlight .c { color: #999; } /* Comment */
3 | .highlight .err { color: #a00; background-color: #faa } /* Error */
4 | .highlight .k { color: #069; } /* Keyword */
5 | .highlight .o { color: #555 } /* Operator */
6 | .highlight .cm { color: #09f; font-style: italic } /* Comment.Multiline */
7 | .highlight .cp { color: #099 } /* Comment.Preproc */
8 | .highlight .c1 { color: #999; } /* Comment.Single */
9 | .highlight .cs { color: #999; } /* Comment.Special */
10 | .highlight .gd { background-color: #fcc; border: 1px solid #c00 } /* Generic.Deleted */
11 | .highlight .ge { font-style: italic } /* Generic.Emph */
12 | .highlight .gr { color: #f00 } /* Generic.Error */
13 | .highlight .gh { color: #030; } /* Generic.Heading */
14 | .highlight .gi { background-color: #cfc; border: 1px solid #0c0 } /* Generic.Inserted */
15 | .highlight .go { color: #aaa } /* Generic.Output */
16 | .highlight .gp { color: #009; } /* Generic.Prompt */
17 | .highlight .gs { } /* Generic.Strong */
18 | .highlight .gu { color: #030; } /* Generic.Subheading */
19 | .highlight .gt { color: #9c6 } /* Generic.Traceback */
20 | .highlight .kc { color: #069; } /* Keyword.Constant */
21 | .highlight .kd { color: #069; } /* Keyword.Declaration */
22 | .highlight .kn { color: #069; } /* Keyword.Namespace */
23 | .highlight .kp { color: #069 } /* Keyword.Pseudo */
24 | .highlight .kr { color: #069; } /* Keyword.Reserved */
25 | .highlight .kt { color: #078; } /* Keyword.Type */
26 | .highlight .m { color: #f60 } /* Literal.Number */
27 | .highlight .s { color: #d44950 } /* Literal.String */
28 | .highlight .na { color: #4f9fcf } /* Name.Attribute */
29 | .highlight .nb { color: #366 } /* Name.Builtin */
30 | .highlight .nc { color: #0a8; } /* Name.Class */
31 | .highlight .no { color: #360 } /* Name.Constant */
32 | .highlight .nd { color: #99f } /* Name.Decorator */
33 | .highlight .ni { color: #999; } /* Name.Entity */
34 | .highlight .ne { color: #c00; } /* Name.Exception */
35 | .highlight .nf { color: #c0f } /* Name.Function */
36 | .highlight .nl { color: #99f } /* Name.Label */
37 | .highlight .nn { color: #0cf; } /* Name.Namespace */
38 | .highlight .nt { color: #2f6f9f; } /* Name.Tag */
39 | .highlight .nv { color: #033 } /* Name.Variable */
40 | .highlight .ow { color: #000; } /* Operator.Word */
41 | .highlight .w { color: #bbb } /* Text.Whitespace */
42 | .highlight .mf { color: #f60 } /* Literal.Number.Float */
43 | .highlight .mh { color: #f60 } /* Literal.Number.Hex */
44 | .highlight .mi { color: #f60 } /* Literal.Number.Integer */
45 | .highlight .mo { color: #f60 } /* Literal.Number.Oct */
46 | .highlight .sb { color: #c30 } /* Literal.String.Backtick */
47 | .highlight .sc { color: #c30 } /* Literal.String.Char */
48 | .highlight .sd { color: #c30; font-style: italic } /* Literal.String.Doc */
49 | .highlight .s2 { color: #c30 } /* Literal.String.Double */
50 | .highlight .se { color: #c30; } /* Literal.String.Escape */
51 | .highlight .sh { color: #c30 } /* Literal.String.Heredoc */
52 | .highlight .si { color: #a00 } /* Literal.String.Interpol */
53 | .highlight .sx { color: #c30 } /* Literal.String.Other */
54 | .highlight .sr { color: #3aa } /* Literal.String.Regex */
55 | .highlight .s1 { color: #c30 } /* Literal.String.Single */
56 | .highlight .ss { color: #fc3 } /* Literal.String.Symbol */
57 | .highlight .bp { color: #366 } /* Name.Builtin.Pseudo */
58 | .highlight .vc { color: #033 } /* Name.Variable.Class */
59 | .highlight .vg { color: #033 } /* Name.Variable.Global */
60 | .highlight .vi { color: #033 } /* Name.Variable.Instance */
61 | .highlight .il { color: #f60 } /* Literal.Number.Integer.Long */
62 |
63 | .css .o,
64 | .css .o + .nt,
65 | .css .nt + .nt { color: #999; }
66 |
--------------------------------------------------------------------------------
/public/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/iilab/contentascode/48a99b3b3381270647a2cf12da0d756b7b06fb3f/public/favicon.ico
--------------------------------------------------------------------------------
/status.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: page
3 | title: Status
4 | ---
5 |
6 | ## Current
7 |
8 | > [Contribute your ideas and discuss the approach of Content as Code #1](https://github.com/iilab/contentascode/issues/1)
9 |
10 | > [Contribute your ideas and follow the discussion about the choice of authoring environment #5](https://github.com/iilab/contentascode/issues/5)
11 |
12 | > [Help develop the proof of concept #7](https://github.com/iilab/contentascode/issues/7)
13 |
14 |
15 |
16 | - [Strategies](#strategies)
17 | - [Implementations](#implementations)
18 | - [Roadmap](#roadmap)
19 | - [Blog](#blog)
20 | - [Wiki](#wiki)
21 | - [Knowledge Base](#knowledge-base)
22 | - [Project Management](#project-management)
23 | - [CMS](#cms)
24 | - [Milestones](#milestones)
25 | - [Proof of Concept - v0.0.1](#proof-of-concept---v001)
26 | - [Prototype - v0.1.0](#prototype---v010)
27 | - [Minimum Viable Implementation - v1.0.0](#minimum-viable-implementation---v100)
28 | - [Follow](#follow)
29 |
30 |
31 |
32 |
33 | ## Strategies
34 |
35 | The below roadmap is only loosely enforced and what drives progress on Content as Code is engagement from projects which are implementing such approaches and will help:
36 | - Develop building blocks with other development stacks
37 | - Extend features of existing building blocks (such as docsmith)
38 | - Participate in the user experience and technology design
39 |
40 | ## Implementations
41 |
42 | - Summary
43 |
44 | | Name | Description | Repo URL |
45 | |-------------------|-----------------------------------|--------------------------------------------------------|
46 | | Content as Code | Reference Implementation | iilab/contentascode |
47 | | Open Integrity | Data Framework | https://code.iilab.org/openintegrity/openintegrity.org |
48 | | Open Mentoring | Mobile Education | iilab/openmentoring |
49 | | Panic Button | Simple CMS for Mobile App | PanicInitiative/PanicButton |
50 | | Using TBB | Semantic Documentation experiment | elationfoundation/using-tor-browser-bundle |
51 | | Security in a Box | Work in Progress | coming soon |
52 | | Level Up | Work in Progress | coming soon |
53 | | TOTEM | Work in Progress | coming soon |
54 | | Advocacy Assembly | Work in Progress | coming soon |
55 |
56 | - Components / Stages
57 |
58 | | Name | Source | Author | Generator | Build | Integration | Publishing |
59 | |-------------------|--------|-----------------------|------------|----------|-------------|-------------|
60 | | Content as Code | Github | Markdown/Pandoc | Metalsmith | npm | Travis | Gh-pages |
61 | | Open Integrity | Gitlab | Prose/Markdown/Pandoc | Metalsmith | Sighjs | Gitlab CI | Self-hosted |
62 | | Open Mentoring | Github | Markdown/Marked | Metalsmith | make | Travis | Gh-pages |
63 | | Panic Button | Github | Prose/Markdown | Jekyll | gh-pages | | Self-hosted |
64 | | Using TBB | Github | Markdown | Jekyll | | | |
65 | | Security in a Box | Gitlab | Markdown | | | | |
66 | | Level Up | Github | | | | | |
67 | | TOTEM | Gitlab | | | | | |
68 | | Advocacy Assembly | Github | | | | | |
69 |
70 | - Publishing Channels
71 |
72 | | Name | Web | Mobile | Book | Interactive |
73 | |-------------------|-----|--------|------|-------------|
74 | | Content as Code | Yes | No | No | No |
75 | | Open Integrity | Yes | | | Yes |
76 | | Open Mentoring | Yes | Yes | Soon | Some |
77 | | Panic Button | Yes | Yes | No | Some |
78 | | Using TBB | Yes | | | |
79 | | Security in a Box | | | | |
80 | | Level Up | | | | |
81 | | TOTEM | | | | |
82 | | Advocacy Assembly | | | | |
83 |
84 | ## Roadmap
85 |
86 | * TOC
87 | {:toc}
88 |
89 |
90 | ### Blog
91 | > In progress
92 |
93 | - [x] Initialise an empty project (`docsmith init metalsmith` (default) or `docsmith init jekyll`)
94 | - [ ] Assist in creating posts (a la Octopress or Docpad)
95 | - [ ] Authoring environment (a la Prose or Gitbook) [#5](https://github.com/iilab/contentascode/issues/5)
96 | - [ ] Validate/Check
97 | - [ ] Preview
98 | - [ ] Publish
99 |
100 | ### Wiki
101 | > In progress
102 |
103 | Some features of a wiki such as the
104 | - [x] Submit page edits
105 | - [ ] Submit anonymous page edits
106 | - [x] View page history
107 | - [ ] Create new pages
108 | - [ ] Semantic features (a la Wagn or Semantic MediaWiki)
109 | - [ ] Federation (a la Smallest Federated Wiki)
110 |
111 | ### Knowledge Base
112 | > Collective Intelligence. See [Open Integrity Framework](https://code.iilab.org/openintegrity/framework)
113 |
114 | - [ ] User Feedback mechanisms
115 | - [ ] Line/Section content review [#37](https://github.com/iilab/contentascode/issues/37) [#38](https://github.com/iilab/contentascode/issues/38)
116 | -
117 |
118 | ### Project Management
119 | > In progress
120 |
121 | - [x] Create tasks (via Github/Gitlab issue)
122 | - [ ] Follow tasks
123 | - [x] Via github/gitlab mentions *(for free)*
124 | - [ ] Via client side widget
125 | - [ ] With a smart notification [#46](https://github.com/iilab/contentascode/issues/46)
126 | - [ ] Update linked task status [#45](https://github.com/iilab/contentascode/issues/45)
127 | - [ ] Link tasks to pages [#24](https://github.com/iilab/contentascode/issues/37) [#38](https://github.com/iilab/contentascode/issues/24)
128 | - [x] See tasks in Kanban view [Leanlabs Kanban #35](https://github.com/iilab/contentascode/issues/35) [Waffle #36](https://github.com/iilab/contentascode/issues/36)
129 |
130 | ### CMS
131 |
132 | - [ ] Content review workflows
133 | - [ ] External review workflows [#20](https://github.com/iilab/contentascode/issues/20)
134 | - [ ] Translation [#4](https://github.com/iilab/contentascode/issues/4)
135 | - [ ] ...
136 |
137 |
138 | ## Milestones
139 |
140 | ### Proof of Concept - v0.0.1
141 |
142 | In the run up to the IFF the proposed tasks to help get the partnership off the ground are:
143 |
144 | #### Design
145 |
146 | - ~~[Iterate on the ecosystem design document #1](https://github.com/iilab/contentascode/issues/1)~~
147 | - ~~[Document translation workflow #2](https://github.com/iilab/contentascode/issues/2)~~
148 | - [Implement translation workflow scripts #3](https://github.com/iilab/contentascode/issues/3)~~
149 | - ~~[Document possible legacy technology constraints and requirements #4](https://github.com/iilab/contentascode/issues/4)~~
150 | - ~~[Choose editor(s) as a basis for the authoring environment #5](https://github.com/iilab/contentascode/issues/5)~~
151 | - ~~[Discuss Roadmap #6](https://github.com/iilab/contentascode/issues/6)~~
152 |
153 | #### Implementation
154 |
155 | - ~~[Implement Proof of Concept #7](https://github.com/iilab/contentascode/issues/7)~~
156 |
157 | > ~~Milestone [Lift off](https://github.com/iilab/contentascode/milestones/Lift%20off)~~
158 | > ~~Version [v0.0.1](https://github.com/iilab/contentascode/issues/7)~~ - https://github.com/iilab/contentascode/issues/7
159 |
160 | - Authoring
161 | + [x] Github
162 | + [x] Jekyll
163 | + [x] Prose
164 | - Translation
165 | + [x] Transifex
166 |
167 | - Collaboration
168 | + [x] Github - Fork and pull request
169 |
170 | - Management
171 | + [x] Waffle
172 |
173 | - CMS Parity
174 | + [ ] Comments - Github issues?
175 | + [ ] Stats - Piwik
176 |
177 | - Deployment
178 | + [ ] Single repo and one click deploy
179 |
180 |
181 | ### Prototype - v0.1.0
182 |
183 | Prototype should allow to do demos and showcase how key functionalities will work and improve existing content workflows.
184 |
185 | > Milestone [Prototype](https://github.com/iilab/contentascode/milestones/Prototype) - https://github.com/iilab/contentascode/milestones/Prototype
186 | > Version [v0.1.0](https://github.com/iilab/contentascode/issues/9) - https://github.com/iilab/contentascode/issues/9
187 |
188 | ### Minimum Viable Implementation - v1.0.0
189 |
190 | Minimum viable implementation which would allow partners to adopt the workflow and technology in production.
191 |
192 | > Milestone [Minimum Viable Implementation](https://github.com/iilab/contentascode/milestones/Minimum%20Viable%20Implementation%20) - https://github.com/iilab/contentascode/milestones/Minimum%20Viable%20Implementation%20
193 | > Version [v1.0.0](https://github.com/iilab/contentascode/issues/8) - https://github.com/iilab/contentascode/issues/8
194 |
195 | ## Follow
196 |
197 | Follow the progress of the Content as Code partnership and contribute:
198 |
199 | - By [commenting and creating github issues](https://github.com/iilab/contentascode/issues)
200 | - By [watching the github repository](https://github.com/iilab/contentascode/subscription)
201 | - By joining us at the [Internet Freedom Festival](https://internetfreedomfestival.org/) content re-use session.
202 |
203 |
--------------------------------------------------------------------------------
/technology.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: page
3 | title: Technology
4 | ---
5 |
6 | > Also see the [status page](../status) and [roadmap](../status#roadmap)
7 |
8 | The following sub-pages describe the various technology related aspect of the content as code project
9 |
10 | * Workflow Components
11 | * [Authoring](authoring)
12 | * [Translation](translation)
13 | * [Collaboration]()
14 | * [Management]()
15 | * [Reuse]()
16 | * [Implementation](implementation)
17 | * [Existing Approaches](existing) : Descriptions of existing approaches among project partners.
18 | * [Inspiration](inspiration) from other projects
19 |
20 |
21 |
22 |
23 | - [Technical Goals](#technical-goals)
24 | - [CMS Parity](#cms-parity)
25 | - [Flexible structure](#flexible-structure)
26 | - [Interoperable and extensible](#interoperable-and-extensible)
27 | - [Streamlined and extensible](#streamlined-and-extensible)
28 | - [Components / Stack](#components--stack)
29 | - [Source](#source)
30 | - [Author](#author)
31 | - [Generate](#generate)
32 | - [Collaborate](#collaborate)
33 | - [Integrate](#integrate)
34 | - [Publish](#publish)
35 |
36 |
37 |
38 | ## Technical Goals
39 |
40 | ### CMS Parity
41 |
42 | > Having usable solutions for commonly available features in CMSes is a design goal.
43 |
44 | Have clear, integrated and open source solutions to deal with comments, visit statistics, search, forms and other features traditionally managed with a database backend.
45 |
46 | ### Flexible structure
47 |
48 | > Allowing completely free form content structures or complex content structures is a design goal.
49 |
50 | ### Interoperable and extensible
51 |
52 | > Allowing mixed workflows that allow importing/exporting/synchronising content across systems and adding software components is a design goal.
53 |
54 | ### Streamlined and extensible
55 |
56 | > Simplicity and ease of use and understanding are design goals.
57 |
58 | Composed of many different software parts, the workflow is nonetheless streamlined and integrated. When deployed with default settings, it can be used immediately. Authors, editors, translators as well as software and systems engineer can understand how the pieces fit together.
59 |
60 | ## Components / Stack
61 |
62 | This table aims to represent which components affect which stages of the content as code framework.
63 | - Key : means that this component is a key component for this stage.
64 | - Change : means that this component modifies or applies to this stage.
65 | - + component : means that this component works better with the specified component.
66 | - = component : means that this component only works with the specified component.
67 | - - component : means that this component doesn't work with the specified component.
68 |
69 | | Component \ Stack | Source | Author | Integrate | Collaborate | Generate | Translate | Publish |
70 | |-------------------|----------|--------|-------------|-------------|----------|-----------|------------|
71 | | github | Key | | + travis | | | | + gh-pages |
72 | | gitlab | Key | | + gitlab-ci | | | | |
73 | |-------------------|----------|--------|-------------|-------------|----------|-----------|------------|
74 | | prose | + github | Key | | | + jekyll | | |
75 | |-------------------|----------|--------|-------------|-------------|----------|-----------|------------|
76 | | travis | | | Key | | | | |
77 | | gitlab-ci | - github | | Key | | | | |
78 | |-------------------|----------|--------|-------------|-------------|----------|-----------|------------|
79 | | validate | | | Change | | | | |
80 | | validate links | | | Change | | | | |
81 | | validate style | | | Change | | | | |
82 | |-------------------|----------|--------|-------------|-------------|----------|-----------|------------|
83 | | jekyll | | | | | Key | | |
84 | | metalsmith | | | | | Key | | |
85 | |-------------------|----------|--------|-------------|-------------|----------|-----------|------------|
86 | | transifex | | | | | | Key | |
87 | |-------------------|----------|--------|-------------|-------------|----------|-----------|------------|
88 | | gh-pages | + github | | | | | | Key |
89 | |-------------------|----------|--------|-------------|-------------|----------|-----------|------------|
90 |
91 | ### Source
92 |
93 | Source repositories which contain the sources for the current project.
94 |
95 | Note: These are not upstream dependencies which will be managed with metadata inside and alongside the source files.
96 |
97 |
98 | ### Author
99 |
100 | This is where the content is edited, manipulated and so on. Different authoring environment will have different capabilities (for instance for validation without a server round-trip or workflow aspects...).
101 |
102 | ### Generate
103 |
104 | The static site generator used.
105 |
106 | ### Collaborate
107 |
108 | Collaborating on the planning, authoring, editing, reviewing, commenting of content.
109 |
110 | ### Integrate
111 |
112 | These are the tools used to prepare and validate content and give feedback to authors and editors, including presenting staging or testing environments/artifacts of various versions that are being worked on.
113 | Note: Maybe this should be included in the publish component.
114 |
115 | ### Publish
116 |
117 | These are the various channels where published versions will be available from.
118 |
--------------------------------------------------------------------------------
/technology/applications.md:
--------------------------------------------------------------------------------
1 | # Applications
2 |
3 | Here are some applications for which Content as Code could be used and implementation notes about what it will take to get there.
4 |
5 | > This should be transcluded from or transclude the [status page](../../status)
6 |
7 | ## Blog
8 | > In progress
9 | > - Docsmith (via Jekyll or Metalsmith component)
10 |
11 | :[Status](../../status#blog)
12 |
13 | ## Wiki
14 | > In progress
15 | >
16 |
17 | :[Status](../../status#wiki)
18 |
19 | ## Knowledge Base
20 | > Collective Intelligence. See [Open Integrity Framework](https://code.iilab.org/openintegrity/framework)
21 |
22 | :[Status](../../status#knowledge-base)
23 |
24 | ## Project Management
25 | > In progress
26 | >
27 |
28 | :[Status](../../status#project-management)
29 |
30 | ## CMS
31 | > In Progress
32 | >
33 |
34 | :[Status](../../status#cms)
35 |
36 | ### Implementation Notes
37 |
38 | Thoughts around how to match certain existing tool's features with a sophisticated Issue tracker (like Github/Gitlab Issues augmented by some form of Kanban)
39 |
40 | - Open Project
41 | + Backlogs -> Could be implemented with Milestones which will also allow to display as groups on Github/Gitlab as well as Swimlanes in Leanlab's Kanban
42 |
43 | - Asana
44 | + Keyboard shortcuts and quick entry
45 | +
46 | - Sprintly
47 | + User story templates
48 | - [Workfront](https://www.workfront.com/enterprise/features/)
49 | + Portfolio management
50 | + Mixed method (agile/waterfall)
51 | - Taiga
52 | - Trello
53 | - Blossom
54 | -
55 |
56 |
--------------------------------------------------------------------------------
/technology/architecture.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/iilab/contentascode/48a99b3b3381270647a2cf12da0d756b7b06fb3f/technology/architecture.png
--------------------------------------------------------------------------------
/technology/authoring.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Authoring
3 | issue: 5
4 | ---
5 |
6 | > [Contribute your ideas and follow the discussion about the choice of authoring environment](https://github.com/iilab/contentascode/issues/5)
7 |
8 | * TOC
9 | {:toc}
10 |
11 | ## Criteria
12 |
13 | The authoring environment should be:
14 |
15 | - **Open source**
16 | - Running in the **browser**
17 |
18 | 6 potential candidate software are considered with these additional criteria:
19 |
20 | - **Markdown support**
21 | - **Git support**
22 | - **Inplace editing**
23 | - **Actively maintained**
24 | - **Extensible**, it should be easy to add functionalities. See [Analysis below](#analysis)
25 |
26 | ---
27 |
28 | | | Markdown | Git | Inplace | Active |
29 | |----------------------------------------------------------|----------|--------|---------|--------|
30 | | [Prose](http://prose.io) | Yes | github | No | No |
31 | | [Gitbook](https://www.gitbook.com/editor) | Yes | git | No | Yes |
32 | | [Dillinger](https://github.com/joemccann/dillinger) | Yes | github | No | |
33 | | [Aloha](http://www.alohaeditor.org/demo/aloha-ui/) | | | Yes | |
34 | | [Pen Editor](http://sofish.github.io/pen/) | Yes | No | Yes | Yes |
35 | | [ContentEditable](http://html5demos.com/contenteditable) | No | No | Yes | Yes |
36 |
37 | ## Feature Gaps
38 |
39 | Based on the [design goals](../../approach#design-goals) the following features should be implemented:
40 |
41 | ### Non negotiables
42 |
43 | - **Media**: Prose for instance manages media if in a single folder. Should have some library features.
44 | - **Links**: Are too easy to break, or complicated to create. Should be checked client side.
45 | - **Metadata**: Even if content is made of several blocks (including reused blocks), they should be invisible and be previewable as a whole, carry invisible metadata and allow various degrees of structure to be enforced.
46 |
47 | ### Nice to haves / Possible Easy Wins
48 |
49 | - **Iconography**: Having an icon library like glyphicons or font-awesome would be... not bad.
50 | - **Forms**: After all that's what GFM ```- [ ]``` are.
51 | - **Diagrams**: Mermaid is where it's at.
52 | - **Offline**: Work offline or with an unhosted approach (remote storage git layer?)
53 |
54 | ### Unicorns
55 |
56 | Let's say goodbye to google docs.
57 |
58 | - **Realtime collaboration**: Substance where have you gone... OT over Git please.
59 | - **Spreadsheet editing**: Quip style of course. There are a number of good looking spreadsheet.js approaches.
60 |
61 | ## Analysis
62 |
63 |
64 | ### Project
65 |
66 | | | OSS | Active | Comment |
67 | |----------------------------------------------------------|-----|--------|------------------------------------------|
68 | | [Prose](http://prose.io) | Yes | No | Huge community of contributors and users |
69 | | [Gitbook](https://www.gitbook.com/editor) | Yes | Yes | |
70 | | [Dillinger](https://github.com/joemccann/dillinger) | Yes | | |
71 | | [Aloha](http://www.alohaeditor.org/demo/aloha-ui/) | | | |
72 | | [Pen Editor](http://sofish.github.io/pen/) | Yes | Yes | |
73 | | [ContentEditable](http://html5demos.com/contenteditable) | No | Yes | |
74 |
75 |
76 | ### Fundamentals
77 |
78 | | | Markdown | Git | Branches | Metadata | Comment |
79 | |-----------|----------|--------|----------|------------------|---------|
80 | | Prose | Yes | Github | Yes | YAML/Frontmatter | |
81 | | Gitbook | Yes | Yes | | | |
82 | | Dillinger | Yes | Yes | | | |
83 | | Pen Edit | Yes | No | | | |
84 | | Substance | No | No | | | |
85 | | Realms | Yes | No | | | |
86 | | PupPub | | | | | |
87 |
88 |
89 | ### UX
90 |
91 |
92 | | | InPlace | Preview | Toolbar | Media | Links | Metadata | Offline | Focused |
93 | |-----------|---------|---------|---------|------------|-------|----------|---------|---------|
94 | | Prose | No | Yes | Yes | Yes | | Yes | No | Yes |
95 | | Gitbook | No | Some | | Yes | | No | Yes? | Some |
96 | | Dillinger | No | | | Yes | | Yes | Yes | Yes |
97 | | Pen Edit | Yes | Yes | | No | | | | |
98 | | Substance | No | Yes | | Yes | | Yes | Yes | Yes |
99 | | Realms | No | Yes | | No toolbar | | No | No | No |
100 | | PupPub | | | | | | | | |
101 |
102 |
103 | ### Tech
104 |
105 |
106 | | | Lang | Frontend | Backend | Modular | Style | Comments |
107 | |-----------|------|----------|-----------------|---------|---------|----------------------------------|
108 | | Prose | JS | Backbone | Quite Stateless | Good | Simple. | Bad code climate. Insecure deps. |
109 | | Gitbook | | | | | | |
110 | | Dillinger | | | | | | |
111 | | Pen Edit | | | | | | |
112 | | Substance | | | | | | |
113 | | Realms | | | | | | |
114 | | PupPub | | | | | | |
115 |
116 | ### Misc
117 |
118 |
119 | | | Offline | Desktop | PDF | Dropbox | G Drive | Comments |
120 | |-----------------|---------|---------|-----|---------|---------|--------------------------|
121 | | Prose | | | | | No | Also has a table editor. |
122 | | Gitbook | | Yes | Yes | | Yes | |
123 | | Dillinger | Yes | | Yes | Yes | Yes | |
124 | | Aloha | | | | | | |
125 | | Pen Edit | | | | | Yes | |
126 | | ContentEditable | | | | | Yes | |
127 |
128 |
129 | ### Prose
130 |
131 | ### Dillinger
132 |
133 | AngularJS - HTML enhanced for web apps!
134 | Ace Editor - awesome web-based text editor
135 | Marked - a super fast port of Markdown to JavaScript
136 | Twitter Bootstrap - great UI boilerplate for modern web apps
137 | node.js - evented I/O for the backend
138 | Express - fast node.js network app framework @tjholowaychuk
139 | Gulp - the streaming build system
140 | keymaster.js - awesome keyboard handler lib by @thomasfuchs
141 | jQuery - duh
142 |
143 | ### Aloha
144 |
145 | ### ...
146 |
--------------------------------------------------------------------------------
/technology/existing.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Existing Approaches
3 | ---
4 |
5 | * TOC
6 | {:toc}
7 |
8 | ## Overview
9 |
10 | | | Content Format | Content Authoring | Content Publication | Content Delivery |
11 | |--------------|----------------|-------------------|------------------------------|----------------------------------|
12 | | SIAB | Wyswiwyg | Drupal | Drupal | Drupal Web |
13 | | Umbrella | Markdown | Manual | SQL -> SQlite DB | Native Android |
14 | | Story Maker | YAML | Git / tx | YAML -> Zipped JSON (Python) | Native Android (StoryPath/Liger) |
15 | | SSD | ? | Drupal | Drupal | Drupal Web |
16 | | Panic Button | Markdown | Prose / tx | md -> JSON (Jekyll) | Native Android (custom) |
17 |
18 | - SIAB uses Drupal and aims to publish or manage content as markdown files. Possibly evolving towards a static Markdown files, possibly evolving to provide a Content API. https://github.com/securityinabox/siabguide
19 | - Umbrella is a native Android app, the content is generated from csv files into an asset database (probably sqlite) in the APK. https://github.com/securityfirst/Umbrella_android
20 | - Story Maker is an Android app using the StoryPath (formerly liger) library to load content packs stored as YAML files. There is a transifex workflow but I'm not sure about how the content is authored. https://github.com/StoryMaker/content-packs https://github.com/StoryMaker/storypath
21 | - EFF uses Drupal. The repo doesn't seem to have the content of the guide. https://github.com/EFForg/ssd
22 | - Panic Button is a native Android app using a custom made JSON file parser to generate its interface (similar but less mature concept than StoryPath). Content is authored in Prose as Markdown and Jekyll generates the JSON files. There's an ongoing effort to interop with Transifex.
23 | - Digital First Aid Kit's source is a git repository of markdown files. Not sure about how the website and printed versions are generated. https://github.com/RaReNet/DFAK
24 | - Level Up uses Drupal. No source code or content I could find.
25 |
26 | ## Interoperability approaches
27 |
28 |
29 | | | Interop Maturity | Rationale |
30 | |-----------------------|------------------|----------------------------------------|
31 | | SIAB | ++ | Markdown in Git / Close to Content API |
32 | | Umbrella | - | CSV / Not Git |
33 | | Story Maker | +++ | Spec and Library |
34 | | SSD | - | No content source ? |
35 | | Panic Button | + | Markdown in Git |
36 | | Digital First Aid Kit | + | Markdown in Git |
37 | | Level Up | -- | No content source / No repo |
38 |
39 | ### Security in a Box.
40 |
41 | Export from SIAB:
42 |
43 | - Ideally access Drupal Nodes through a granular API (at the level of sections, community snippets), keep track of upstream last modified date and translation dependencies to flag downstream update needs and generate/transform into static source for content packs.
44 |
45 | Import in SIAB:
46 |
47 | - Drupal Remote Entity or Web Service Data module consuming a statically generated
48 |
49 | Integration Path
50 |
51 | - Possible to reuse Open Mentoring/StoryPath approach to generate content packs from SIAB to create a SIAB Mobile App.
52 |
53 | ### Umbrella.
54 |
55 | Export from Umbrella:
56 |
57 | - Directly by transforming source csv files
58 |
59 | Import in Umbrella:
60 |
61 | - Exporting Open Mentoring Content Packs as Umbrella compatible CSV
62 |
63 | Integration Path
64 |
65 | - Umbrella could reuse a Content Pack approach and propose to StoryPath to integrate Checklist in the spec
66 |
67 | ### Story Maker
68 |
69 | Export/Import from Story Maker
70 |
71 | - Compatibility with OBB Content Pack binaries should mean that they can just be an additional source to download from.
72 |
73 | Integration Path
74 |
75 | - Working with StoryPath to upstream different approaches to content management and developing NativeScript/Cordova plugins might pay off.
76 |
77 | ### Panic Button
78 |
79 | To be discussed but if the Panic Button help section was rewritten to allow loading StoryPath content packs that would probably be a good thing.
80 |
81 | ### TOTEM
82 |
83 | Interop with practical tests is a strong lead.
84 |
85 | ### Open Mentoring
86 |
87 | #### Content Requirements
88 |
89 | - Git managed static content approach
90 | - Transifex workflow
91 | - Known interop path with *all* content ecosystem
92 |
93 | #### Tech Options
94 |
95 | Format
96 |
97 | - Markdown with YAML Frontmatter in smaller chunks than StoryMaker Content Packs (to allow markdown bodies in cards)
98 |
99 | Authoring
100 |
101 | - Prose
102 |
103 | Publication
104 |
105 | - Maybe Liger content pack interop?
106 |
107 | Delivery
108 |
109 | - Native Android with StoryPath/Liger and different git static content publication scripts.
110 | - NativeScript App with StoryPath/Liger
111 | - NativeScript App with StoryPath/Liger compatible approach
112 | - Corbova App with StoryPath/Liger
113 | - Corbova App with StoryPath/Liger compatible approach
114 |
115 | See [Technical Research Wiki Page](https://github.com/iilab/openmentoring-content/wiki) for more about platform choice.
116 |
--------------------------------------------------------------------------------
/technology/foundations/git.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: git
3 | stage: source
4 | ---
5 |
6 | # Git
7 |
8 | One of the most fundamental components of the content as code approach is the use of the distributed version control system git. It provides low level facilities for tracking changes and backing up ~~code~~ content in large file structures, create new versions (branches) as well as ways to deal with conflicts and merging different versions.
9 |
10 | But one of the emerging practices that both Github and Gitlab have been focusing on have added a number of buildinb blocks to the low-level mechanics of git. Some of these are:
11 | - forks and tracking the "fork graph",
12 | - pull requests as a first class concept,
13 | - continuous integration reporting back at various levels (release, branches, pull requests)
14 | - issue tracking deeply integrated with commits,
15 | - code review tools,
16 | - collaboration with @mentions and #issue references across repos.
17 |
18 | It is really these emerging tools that offer the most promise in applying "code management" concepts to "content management".
19 |
20 | One of the strategies of content as code is, in addition to having a author-centric approach to prioritising features and improving user experience, to follow a somewhat bottom-up, tech-centric approach simultaneously which aims to iterate on the above building blocks to see how well they can be assembled to provide new useful functionalities for content management.
21 |
22 | Some of these ideas are currently being explored in the following issues on the content as code repo:
23 | - [Use of continuous integration to provide content verification and testing (#11)](https://github.com/iilab/contentascode/issues/11)
24 | - [Reporting of these tests, such as link checking, in pull requests (#11)](https://github.com/iilab/contentascode/issues/11#issuecomment-196234329)
25 | - [Implement github issues as a page discussion feature (#24)](https://github.com/iilab/contentascode/issues/24)
26 | - [Integration with waffle.io (#35)](https://github.com/iilab/contentascode/issues/35)
27 | - [Integration with kanban.leanlabs.io (#36)](https://github.com/iilab/contentascode/issues/36)
28 |
--------------------------------------------------------------------------------
/technology/foundations/github.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Github
3 | stage: source, author, collaborate, publish
4 | ---
5 |
--------------------------------------------------------------------------------
/technology/foundations/gitlab.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Gitlab
3 | stage: source, author, collaborate, integrate
4 | ---
5 |
--------------------------------------------------------------------------------
/technology/foundations/markdown.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: markdown
3 | stage: author
4 | ---
5 |
6 | # Markdown
7 |
8 |
--------------------------------------------------------------------------------
/technology/foundations/prose.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Prose
3 | stage: author
4 | issue: 47
5 | ---
6 |
7 | - Integrate with Gitlab backend
8 | - Easier "Fork and Pull Request" workflow for non techies.
9 | - Allow offline workflow
10 | - Metadata first document creation
11 | - Transclusion support (iilab/prose#1)
12 | - Prosemirror integration
13 | - Content "Integration" tests #11 (perhaps with isomorphic tests ran by prosemirror in the client)
14 |
15 |
16 | :[Choose editor(s) as a basis for the authoring environment #5 - Comment](https://github.com/iilab/contentascode/issues/5#issuecomment-197972547)
17 |
18 | This [issue on ProseMirror](https://github.com/ProseMirror/prosemirror/issues/9) makes a good point about separation of concern between the editor and the backend. Substance might mean a slightly stronger coupling between document authoring, document metadata and project navigation and backend.
19 |
20 | In that sense Prose could be a project navigation component with ProseMirror as the authoring component (there would probably need to be some integration between the two to help for instance with navigation within a project's media or link library). Prose would manage document metadata (in the YAML frontmatter or elsewhere) and connect to various backends (including local ones for offline editing).
21 |
22 | This gitbook component Repofs (https://github.com/GitbookIO/repofs) is an interesting approach to integrating the project navigation (and common features currently not in Prose like moving files, creating folders or dealing with templates.
--------------------------------------------------------------------------------
/technology/implementation.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Implementation
3 | ---
4 |
5 | > See the **work in progress for the [docsmith](docsmith) reference implementation**
6 |
7 | > Also see the [status page](../../status) and [roadmap](../../status#roadmap)
8 |
9 | ## Developer Experience
10 |
11 | Focus on allowing user to start from a project scaffold:
12 |
13 | - a Blog (Jekyll compatible) with added "Contribute to this page" links.
14 | - a Wiki (Gollum compatible)
15 | - a Resource website
16 | - a Software documentation site
17 |
18 | We could create repos (```contentascode-blog```, ```contentascode-wiki```, ```contentascode-site```, ```contentascode-doc```) that are ready to clone with some sensible defaults.
19 |
20 | The default pipelines would have a travis.yml that push to a ```gh-pages``` branch.
21 |
22 | We could also look into Grunt-init or Yeoman Project Scaffolding tools to allow configuration of various options such as:
23 |
24 | - Choice of templating language and other frontend framework choices
25 | - Choice of integration backend (Jekyll/Metalsmith/...)
26 | - Choice of a theme (Bootstrap and variants, Foundation, GH Pages themes...)
27 | - Adoption of metadata schemas (SPAR, Provenance, DigiSec Taxonomy).
28 | - Configuration of tools like Prose with good usable defaults.
29 | - Enabling of other CI backends (Gitlab CI, Jenkins, Thoughtworks Go,...)
30 | - Configuration, integration and deployment (Heroku button style) of micro-services (like commenting, stats,...)
31 |
32 | We also need to think about migration and various options to use [integrations](https://github.com/iilab/contentascode/labels/integration) to facilitate a progressive transition process from CMSes to the content as code approach.
33 |
34 | ## Reference Implementation Matrix
35 |
36 | | Name | Description | Repo | Editor | Generator | Build | Hosting | Services |
37 | |-----------------------------------|------------------------------------------|--------|--------------|------------|--------------|-------------|------------------|
38 | | scaffold-github-pages | Fork and play. | Github | Prose | Jekyll | Github Pages | Github | |
39 | | scaffold-github-jekyll-travis | With Jekyll and Travis CI | Github | Prose | Jekyll | Travis | Github | |
40 | | scaffold-github-metalsmith-travis | With Metalsmith and Travis CI | Github | Prose | Metalsmith | Travis | Github | |
41 | | scaffold-jekyll-jenkins | Open source stack | Gitlab | Hosted Prose | Jekyll | Jenkins | Self-Hosted | |
42 | | scaffold-metalsmith-gitlabci | Open source stack with metalsmith | Gitlab | Hosted Prose | Jekyll | Gitlab CI | Self-Hosted | |
43 | | infra-heroku | Push to deploy micro-service infra | Gitlab | Hosted Prose | Jekyll | Jenkins | Heroku | Single container |
44 | | infra-docker | Docker single server micro-service infra | | | | | | Multi-container |
45 | | infra-ansible | Distributed micro-service infra | | | | | | Multi-server |
46 |
47 | ## Modularity
48 |
49 | Scaffold and infrastructure repos might make some choices with regards to lower level implementation approaches (make vs bash vs gulp...) and it would be good to allow this to be plug and play. i.e. Content as Code should be opinionated with regards to concepts and architecture (and maybe its pivot data format, metadata description and other declarative things about workflow configuration), but not with regards to implementation.
50 |
51 | This table aims to represent which components affect which stages of the content as code framework.
52 | - Key : means that this component is a key component for this stage.
53 | - Change : means that this component modifies or applies to this stage.
54 | - +1 component : means that this component works better with another component.
55 | - -1 component : means that this component doesn't work with another component.
56 |
57 | | Component \ Stage | Source | Author | Build | Integrate | Translate | Publish |
58 | |-------------------|-----------|--------|-----------|--------------|-----------|-------------|
59 | | github | Key | | | +1 travis | | +1 gh-pages |
60 | | gitlab | Key | | | +1 gitlab-ci | | |
61 | | prose | +1 github | Key | +1 jekyll | | | |
62 | | jekyll | | | Key | | | |
63 | | metalsmith | | | Key | | | |
64 | | travis | | | | Key | | |
65 | | gitlab-ci | -1 github | | | Key | | |
66 | | linkchecker | | | | Change | | |
67 | | transifex | | | | | Key | |
68 | | gh-pages | +1 github | | | | | Key |
69 |
70 | | Components \ Stages | Store | Edit | Share | Check | Translate | Publish |
71 | |---------------------|-------|------|-------|-------|-----------|---------|
72 |
73 |
74 |
--------------------------------------------------------------------------------
/technology/implementation/docsmith.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: docsmith
3 | source: https://github.com/contentascode/docsmith/README.md
4 | ---
5 |
6 | > An npm module called [docsmith](https://www.npmjs.com/package/docsmith) has been published with the following README.md
7 |
8 | # This README is out of date and should benefit from dependency tracking! See the [current README here](https://github.com/contentascode/docsmith/blob/master/README.md)
9 |
10 | Content as Code aims to make it easy to start a website in just a few steps but also build complex content publishing pipelines. It develops best practices to managing content workflows inspired from how code is managed in large collaborative software engineering projects.
11 |
12 | **docsmith** implements the Content as Code framework using metal*smith*, pan*doc* and *doc*ker microservice deployment.
13 |
14 | ## Getting Started
15 |
16 | The simplest way to get started is to fork one of our sample repos on github:
17 | - https://github.com/contentascode/ blog: A template for a simple blog
18 | - https://github.com/contentascode/ wiki: A template for a wiki
19 | - https://github.com/contentascode/ doc: A template for software documentaiton
20 | - https://github.com/contentascode/ site: A template for a simple website
21 |
22 | You can have these templates up and running simply by [activating Github pages on your fork](). This will make the site available after a few minutes on http://USER.github.io/REPO where ORG is the name of the user or organisation which forked the repo, and REPO is the name of the REPO (which should be blog or site, unless you renamed it.)
23 |
24 | Wow, that was easy and fast. What can I do next?
25 |
26 | ### Use your own domain name
27 |
28 | You can make your new site available on the domain name of your choice. If you have procured a domain name you can simply create a CNAME file at the base of this repository and point your DNS following these instructions.
29 |
30 | ### Collaboration
31 |
32 | The Content as Code workflow uses best practices to allow different people to contribute to your content project, in the way that large software engineering projects in the open source world do it.
33 |
34 | The sample repos use Github (soon Prose) to help with content editing. By default, all pages of your new website have built in links to
35 |
36 | ### Checking Links
37 |
38 | You can go to the next level by using another free online service (Travis CI) to build your site. This will provide you with additional features such as using validations. For instance to check that links are working or that your content is generally well formatted and readable. You can activate travis by going to travis-ci.com signing up and activating travis for your USER/REPO project.
39 |
40 | Is that it? Yes, now you'll receive emails with notifications each time there is a problem with your website build, like a broken link or possible other problems with your site.
41 |
42 | (Open an issue to report broken link, replace with an archive.org link if broken link!)
43 |
44 | ### Choose a theme
45 |
46 | You can change our default website layout and theme if you have activated Travis CI in the previous step. In that case, you can edit the docsmith.yml file and change the theme to another content as code enabled jekyll theme we support.
47 |
48 | ### What next?
49 |
50 | We're planning to implement many more features with a content as code approach for instance doing diagrams, interactive content, or integration with and migration from your existing content management system.
51 |
52 | If you want to go deeper into **docsmith** and content as code, you can also help us develop the command line tool we have started designing below which will help more advanced users with more sophisticated content management needs. It is based on a modular approach
53 |
54 | ## Docsmith CLI tool
55 |
56 | - ```npm install -g docsmith``` : installs content CLI tool.
57 |
58 | - ```docsmith init```: Or ```docsmith init ``` like ```docsmith init blog```, ```docsmith init doc``` or ```docsmith init wiki```.
59 | - ```docsmith install``` : in a repo would read content.yml and create package.json, metalsmith.json and docker-compose.json and run necessary installations (npm install,...).
60 | - ```docsmith install validator``` : Install default plugin suite in validator (linkchecker) or the one specified in the docsmith.yml file.
61 | - ```docsmith install validator styleguide```: Install specific plugin (and updates the yml file)
62 |
63 | - ```docsmith build```: Build the content locally.
64 | - ```docsmith serve```: Serve the content locally. (Should probably open a console and allow to `pull`,`update` or `pull` within it)
65 | - ```docsmith publish```: Publishes the content (and configure and/or deploy needed microservices).
66 |
67 | - ```docsmith load/pull``` : Get local content updates
68 | - ```docsmith load/pull git clones
the PanicButton Android application's asset repository. The script then converts all of the markdown files in \_posts/mobile and \_posts/help (including all files in the \_posts/mobile/\git add -A && git commit -m "Updating translations to the PanicButton Application" && git push origin dev
. If the newly created JSON files, mobile_\git push
that called the script represents an updated translation), then the changes will be committed and pushed to the PanicButton Android Application's repository. This triggers a rebuild of the app. If the JSON files, mobile_\git add -A
, and so the git commit && git push origin dev
will fail without triggering an error.
70 |
71 | ### Panic Button Android App Additional Transifex workflow
72 |
73 | #### strings.XML
74 |
75 | **[Status: .tx config creation in progress. TXGH integration TODO]**
76 |
77 | The PanicButton Android app contains an additional Transifex workflow. The app has translatable material independent of the panicbutton.io source files in the **/src/main/res/values/strings.xml** file.
78 |
79 | Thus, the PanicButton Android Application repository also houses a .tx folder with its own config file, which dictates the translation source, resulting file names, and format for **strings.xml**.
80 |
81 | A TXGH integration in the PanicButton app repository will register a pushed change in the **strings.xml** file, updating **strings.xml** in the Transifex repository to show that translation is no longer complete and alerting translators that an update to the translation is necessary.
82 |
83 | Upon completion of the translation, TXGH will return the translated files to the PanicButton repository, placing them in the directories **/src/main/res/values-\