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

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

Đang mở
#253 2 bình luận 1 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Ngôn ngữ chính
JavaScript
Star
172
Fork
142
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

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)

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Xem xét luồng hiện tại qua tests/dummy/app, đặc biệt là router.js, các tệp Markdown của route và section/template.hbs. Xác định cách một cây docs/, front matter, các tệp _nav.md và những thay đổi được theo dõi sẽ được ánh xạ vào ứng dụng dummy; hoàn thành nghĩa là contributors có thể viết Markdown mà không phải tự tạo các route hoặc template Ember.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
javascript, markdown
Lĩnh vực
documentation, tooling
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Cần làm rõ
Mức phù hợp với người mới
25/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.