ember-learn / ember-learn/ember-cli-addon-docs

Make writing docs easier (for non-tech/ember people)

オープン
#253 コメント 2 件 リアクション 1 件 担当者 0 名 GitHub で見る
主要言語
JavaScript
スター
172
フォーク
142
PR マージ指標
30日以内にマージされた PR はありません

説明

At the moment, writing pages for ec-addon-docs that requires you to do the following:

- Find `tests/dummy/app` folder
- Create a route in `tests/dummy/app/router.js`
- Create the respective `my-route.md` (or `my-route/template.md`) file
- Possibly create a `section/template.hbs` for the layout of a new section

This is not hard to do for us ember folks but if other people (e.g. designers) jump in and want to provide texts they probably have a hard time doing so (just try to remember that cryptic folder path to the dummy app might be exhausting enough). There should be an easier way. An easy shot might be the following (a little jekyll inspired):

- Leverage the `docs/` root folder
- People will use folders inside for different sections
- They will only write markdown
- Markdown contains a front matter (delimited via `--`)
- Front Matter contains meta data (e.g. `layout`)
- e.g. `layout` is predefined by a developer and maps to the respetice `section/template.hbs`
- `docs/` folder has some "magic" meta files (starting with underscore). Those meta files will provide navigation for various sections

An example:

```
- docs
- sandbox
- _nav.md
- index.md
- quick-start.md
```

The `docs` folder can be watched and will be hoisted/mapped into the dummy app, creating routes on the fly =) (can be optimized on release)

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

tests/dummy/app を通る現在のフローを、特に router.js、ルートの Markdown ファイル、section/template.hbs について確認します。docs/ ツリー、front matter、_nav.md ファイル、監視対象の変更を dummy app にどのようにマッピングするかを定義します。完了の基準は、contributor が Ember の route や template を手動で作成せずに Markdown を書けることです。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
javascript, markdown
領域
documentation, tooling
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
説明が足りない
初心者へのやさしさ
25/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。