rheehot/open-source

오픈소스SW입문 수업에서 진행한 프로젝트로 VScode를 이용한 마크다운 편집기 (학교 깃랩에서 깃헙으로 미러링)

4조 Project

1. 프로젝트 이름

-

Visual Studio Code를 이용한 Markdown 편집기

2. 팀멤버 및 각 역할

이름	역할
김창희(소프트웨어학과)	자료조사, docs 오픈소스 코드 기능 변경 및 개선, README 파일 제작
박승세(소프트웨어학과)	자료조사, pandoc 오픈소스 코드 기능 변경 및 개선, README 파일 제작
정소희(소프트웨어학과)	아이디어 제공, 자료조사, phantomjs 오류 도움말 추가(pdf 기능 개선), 로고&ppt 및 README 파일 제작
서동훈(수학과)	아이디어 제공, 자료조사, README 파일 제작

3. 개발 동기 및 과정

• 개발동기

  • 오픈소스 프로젝트를 진행하면서 git에서의 Markdown을 사용해보았다.

  • git에서의 Markdown의 경우 문법에 대한 도움 기능이 없기때문에 사용하고자하는 문법을 검색엔진을 통해 알아봐야했고, 또 git에서는 지원하지 않는 문법들이 존재하여 그것을 대체할 다른 문법을 찾아보는 등 다양한 어려움이 있었다.

  • git의 Markdown에서는 현재까지 작업한 결과물을 확인하려면 작업중 일일히 Commit을 하거나 별도의 창으로 지원하는 Preview를 활용해야만 했었다. 따라서 prewiew 기능을 사용하는 것은 번거로웠고 현재 작업 진행 상태를 실시간으로 보면서 수정이 불가능했다. 이런 환경에서 Markdown 작업은 매우 답답하고 불편했다.

  • Markdown의 편리함을 많은 개발자들에게 제공하고자 이 오픈소스를 개발하게 되었다.

• 개발과정

  • Vscode에서는 편집기의 시각화가 매우 편하기 때문에 Vscode에서 Markdown을 사용할 수 있는지에 대한 아이디어를 생각했다. (시각화 : 사용하면 자동 줄 맞춤, 색 구분 등)

  • Vscode에서 Preview 동기화를 지원하고 내부 창에서 실시간으로 확인가능한 Markdown 오픈소스가 있는지 조사했다. -> vscode-markdown-preview-enhanced

  • Vscode에서 Markdown의 문법을 간소화할 수 있고 문서 스타일을 쉽게 편집할 수 있는 가장 적합한 오픈소스를 조사했다. -> vscode-docs-authoring

  • Vscode에서 Markdown으로 작업한 것을 바로 word형식으로 저장해주는 오픈소스를 검색했다. -> vscode-pandoc

  • 위의 오픈소스들을 가지고 사용시 간략한 설명문 및 사용방법을 한글화 하기위해 코드를 개선하여 사용자가 편리하게 이용하게끔 수정했다.

4. 프로젝트 내용

기존 Markdown의 불편함

1. Preview기능

   • git의 Markdown 작업에서 동기화된 미리보기 기능을 활용하려면 Preview창에 들어가서 확인하고 다시 Write 창을 봐야하기 때문에, commit시에 실제 git에 나타나는 형식이 다르게 표현되는 불편함이 존재한다.

     

2. Markdown문법의 어려움

   • Markdown을 사용하다 보면 image, video 삽입 등 문법의 어려움과 생소한 기능들이 존재하여 검색을 통해 알아야 하는 불편함이 존재한다.

   

기존의 Markdown 편집기

1. Typora

- 프리뷰 화면에서 수정이 가능함 (WYSIWYG 방식), 다양하고 깔끔한 테마와 레이아웃 / 테마 CSS 직접 수정 가능, 멀티 플랫폼 지원, 베타 기간 중 무료 LaTeX / 테이블 / UML Diagram 지원, 포커스 모드 / 타자기 모드 가능. - 하지만 단점은 베타버전이라 버그가 존재하며, 베타기간만 무료라는 것이다. 결국 유료인 편집기.

2. Bear

- 다양한 테마와 깔끔한 레이아웃, 문서 간 링크 기능, 태그 및 아카이브 기능, 다양한 배포 옵션 지원, 앱과 자유로운 연동 (동기화) - 하지만 애플 계열만 지원하며 폴더 미지원으로 다량의 문서 분류가 불편

3. Byword 2

- 방해받지 않고 집중할 수 있는 간결한 디자인, 깔끔한 테마 2종 (Light, Dark), 다양한 배포 (Medium, WordPress, tumblr, Blogger, Evernote), iCloud Drive 지원 - 하지만 프리뷰 화면으로 전환이 불편하며 macOS 와 iOS 따로 구입 필요, 애플 계열만 지원, 유료

4. ulysses 3

- 다른 에디터들에 비해 전문적이고 많은 기능을 제공함, 장문의 책 등을 쓰기에 최적화 됨 - 예전에는 최초 결제 후 영구 사용이었던 방식이었으나 현재는 매달 이용료를 내는 구독 방식으로 바뀜. 이미 구입한 사람들도 사용하려면 매달 돈을 내야해서 일부 사용자들의 반발이 있었음.

4. StackEdit

- 브라우저 기반으로 별도의 소프트웨어 설치 필요 없고 어디서든 접속 가능, 브라우저 로컬 스토리지에 저장 + 계정 연동 시 온라인에 저장 가능 (Google Drive 등), 다양한 배포 옵션 (Google Drive, Dropbox, Github, Wordpress, Blogger 등), 내부에 마커 형식으로 메모처럼 코멘트를 달 수 있음 (구글 계정 로그인 필요), KaTeX / 테이블 / UML Diagram - 하지만 오프라인 시 사용 제약, 온라인 스토리지 연동 안할 경우 데이터 손실 위험, 테마 변경 기능 없음

5. Inkdrop

- 다양한 플랫폼 지원, 노트북 형식으로 폴더 지원, 태그 + 4가지 상태 (Active, On Hold, Completed, Dropped)로 분류 가능, 자체 패키지 매니저 ipm 이 있어서 오픈소스 플러그인으로 확장 기능 설치 가능 - 하지만 속도가 비교적 느림, 디자인이나 UI가 비교적 떨어지고 유료

기능 설명

1. Preview

   • Vscode에서 현재 자신이 작성하고 있는 Markdown의 변경 내용을 별도의 처리 없이 Preview를 통해 실시간으로 확인 가능
   • Markdown preview 지원으로 github와 동일하게 작동하여 편리하게 사용 가능

2. Word의 문서 편집 기능 추가

   • Word의 글꼴 편집, table 삽입 등의 기능 추가로 문서의 스타일을 편집하는 기능을 지원

3. 기능 설명 한글화

   • 기존에 영어로 되어있던 함수 설명, 기능 설명 등을 한글화하여, 평소 영어 해석에 어려움을 느꼈던 사용자도 손쉽게 기능 이해

4. 문법 간소화

   • Word를 통해 기존 Markdown의 문법을 간소화 시킴으로써 Markdown의 문법을 몰라도 최소한의 학습으로 사용 가능

5. Word 저장기능

   • 작성한 Markdown을 Preview에서 보여지는 그대로 간편하게 Word로 저장 가능

기대 효과

1. Markdown 작성에 대한 실시간 동기화를 지원해 개발자의 Markdown사용 편리함을 극대화

2. Word 기능을 이용해 Markdown 입문 개발자들이 겪는 Markdown 문법의 어려움을 최소화, 간편하게 문서의 스타일 편집 가능

3. Mac OS에서 Markdown 편집기들의 유료화에 대한 문제점 해소

4. Preview를 보기 위해 Github에 접속할 필요가 없어서 별도의 네트워크 연결이 없이도 작성 후 문서화 가능

오픈소스 사용하는 법

• 설치경로

  C:\Users\사용자계정아이디\ .vscode\extensions

  위의 경로에 다운받은 폴더4개를 옮기기

• docs기능 사용법

  • Docs Markdown에 접그한기 위해 type ALT+M 입력.
  • 원하는 기능을 선택하기 위해 클릭하거나 위쪽/아래쪽 화살표를 사용하여 필터링을 시작한 다음, 메뉴에서 원하는 기능이 강조 표시되면 'ENTER'를 누르십시오.
  • DOCS 오픈소스 제공되는 기능은 아래와 같습니다.

Function	Command	Description
굵게쓰기	formatBold	글자를 굵게 바꿈.
기울임체	formatItalic	글자를 기울이게 바꿈.
블록화	formatCode	문장이나 그 이하가 선택되면, 글자를 블록화처럼 바꿔줌. 여러 줄을 선택하면 분리 된 코드 블록으로 서식을 지정하고 OPS에서 지원하는 프로그래밍 언어를 선택적으로 선택할 수 있습니다. 언어를 선택하지 않으면 빈 분리 (fenced) 코드 블록을 삽입합니다.
알림기능	insertAlert	메모, 중요, 경고 또는 팁 삽입. 메뉴에서 경고 종류를 선택한 다음 경보 유형을 선택하십시오.이전에 텍스트를 선택한 경우 선택한 경고 구문으로 둘러싸이게됩니다. 텍스트를 선택하지 않으면 자리 표시 자 텍스트가있는 새 경고가 추가됩니다.
번호 목록	insertNumberedList	새 번호 매기기 목록 삽입. 여러 줄을 선택하면 각 줄이 목록 항목이됩니다. 번호 매기기 목록은 모두 1로 Markdown에 표시되지만 docs.microsoft.com에서 연속 번호 또는 중첩 목록의 경우 문자로 렌더링됩니다. 중첩 된 번호 매기기 목록을 만들려면 상위 목록에서 탭을 선택합니다.
점 목록	insertBulletedList	새로운 점 목록 삽입.
테이블	insertTable	Markdown 테이블 구조를 삽입합니다. 테이블 명령을 선택한 후 3 : 4와 같은 형식 열 : 행의 열과 행 수를 지정하십시오. 이 확장 프로그램을 통해 지정할 수있는 최대 열 수는 5 개이며 가독성을 위해 권장되는 최대 값입니다.
저장소 파일과 연결	selectLinkType	링크 삽입. 이 명령을 선택하면 다음 하위 메뉴가 나타납니다. External: URI로 웹 페이지에 링크. "http" 나 "https"를 필수로 포함해야됨. Internal: 동일한 repo에있는 다른 파일에 대한 상대 링크를 삽입하십시오. 이 옵션을 선택한 후 명령 창에 파일 이름을 입력하고 원하는 파일을 선택하십시오. Bookmark in this file: 올바른 형식의 책갈피를 삽입하려면 현재 파일의 제목 목록에서 선택하십시오. Bookmark in another file: 먼저 파일 이름별로 필터링하고 연결할 파일을 선택한 다음 선택한 파일에서 적절한 제목을 선택하십시오.
이미지 삽입	insertImage	대체 텍스트 (액세스 가능성에 필요함)를 입력하고 선택하고이 명령을 호출하여 repo에서 지원되는 이미지 파일 목록을 필터링하고 원하는 것을 선택하십시오. 이 명령을 호출 할 때 대체 텍스트를 선택하지 않은 경우 이미지 파일을 선택하기 전에 대체 텍스트를 묻는 메시지가 표시됩니다.
파일 포함시키기	insertInclude	현재 파일에 내장시킬 파일 찾음.
스니펫	insertSnippet	현재 파일에 내장시킬 snippet코드를 repo에서 찾음 .
비디오 삽입	insertVideo	내장된 비디오 추가.
미리보기	previewTopic	DocFX 확장을 사용하여 나란히있는 창에서 활성 주제를 미리 봅니다. DocFX 확장이 설치되어 있지 않거나 설치되어 있지만 비활성화되어 있으면 해당 항목이 렌더링되지 않습니다.

• Preview기능 사용법

  • 파일 형식 .md로 지정
  • 다음 그림 파일에 표시되는 아이콘 클릭

• Word기능 저장 사용법

  1. 저장시 마크다운 파일이 열려있어야 하며, 기능을 돌리는 방법은 아래의 두가지 방법이 존재합니다.
  2. F1 윈도우에서 입력(shift+cmd+P Mac에서 입력), pandoc입력 후 + `Enter'
  3. 또는 -ctrl+K then P 입력(맥에서는 cmd+K 입력 후 P 입력)

오픈소스 사용시 팁

The cmd key for Windows is ctrl.

Shortcuts	Functionality
cmd-k v	미리보기창 열기
ctrl-shift-s	미리보기 동기화 / 소스 동기화
shift-enter	코드 묶음 실행
ctrl-shift-enter	모든 코드 묶기
cmd-= or cmd-shift-=	미리보기 확대
cmd-- or cmd-shift-_	미리보기 축소
cmd-0	미리보기 초기화
esc	사이드바 TOC 전환

기존 오픈소스에 issue 제안

• Microsoft/vscode-docs-authoring 기존 오프소스 에러에 pont의 크기 조절 기능 제시

• dfinke/vscode-pandoc 기존 오픈소스 사용시 pdf 에러 발생 및 원인 제시

• shd101wyy/vscode-markdown-preview-enhanced 기존 오픈소스에 DOCS기능 추가 제시

• shd101wyy/vscode-markdown-preview-enhanced pdf변환시 뜨는 특정 오류에 대한 해결법 제시 및 해결법 명시 제안

실행 예시

1. preview를 통해 번호 매기기, 테이블 생성하기, 사진 추가하기

2. docx 파일로 변환

이 오픈소스를 사용하고자 하는 SW개발자에 도움이 되는 것

1. Markdown 작성에 대한 실시간 동기화를 제공하기 때문에 편리하게 Markdown을 사용 할 수 있다. 몇몇 Markdown 편집기들은 preview를 지원하지 않기 때문에 자신이 작성하고 있는 Markdown code가 어떻게 보여지고 있는지 알 수 없어서 작업의 속도가 느리며, 계속되는 수정 작업에도 Preview 창을 일일히 확인 해야했기 때문에 번거로움이 있었다. 하지만 이 편집기를 사용한다면, 내부의 preview로 자신의 작성 결과물을 확인하면서 수정,보안할 수 있기 때문에 시간의 효율성과 사용자의 편리함이 증가한다.

2. Word의 기능을 추가해 Markdown 문법의 어려움을 최소화해서 입문하기 부담이 없고, 익숙한 환경속에서 문서의 스타일 편집할 수 있다. 입문 개발자들에게 가장 어려운 것은 언어의 어려움일 것이다. 새로운 언어를 터득하고 익숙해 지는데 걸리는 시간은 있으므로, 편리한 기능을 두고도 이용하지 못하는 개발자들도 다수 생긴다. 이러한 문제점을 없애기 위해 우리는 Word의 기능을 이용해 Markdown의 문법을 더욱 쉽게 간소화하였다. Markdown의 문법을 이제 막 배우는 개발자라도 이 편집기를 사용하면 Markdown으로 편리하게 원하는 결과물을 만들어 낼 것이다.

3. Mac OS를 사용하는 개발자, Windows를 사용하는 개발자 모두 무료로 편리한 기능을 사용할 수 있다. 무료인 Markdown 편집기도 있지만 유료인 편집기도 다수 존재한다. 특히, Mac OS를 지원하는 편집기들은 대부분 유료이다. 따라서 편집기를 사용하기 위해서는 비용을 지불해야 한다는 단점이 존재했다. 이 편집기를 사용하면 개발자들이 비용에 대한 부담없이 다양한기능을 사용할 수 있다.

4. Preview를 오프라인 상황에서도 제공하므로 별도의 네트워크 연결이 없이도 코드 작성이 가능하고 더불어 문서화가 가능하다. 항상 온라인 상황에 있을 수는 없으므로 불가피하게 오프라인 상태에서 문서를 작성해야 할 때가 존재한다. 이 편집기는 오프라인 상황에서도 Preview를 활용하면서 Markdown 작업을 할 수 있다.

5. 사용되는 Github 오픈소스 SW 목록

• Microsoft/vscode-docs-authoring: https://github.com/Microsoft/vscode-docs-authoring
• shd101wyy/vscode-markdown-preview-enhanced: https://github.com/shd101wyy/vscode-markdown-preview-enhanced
• dfinke/vscode-pandoc: https://github.com/dfinke/vscode-pandoc

6. 이 작업 이후, 추가적으로 진행되면 좋을 작업들

• android, ios 앱 지원
• 가장 표준화된 markdown 문법 확보 후 tutorial 서버지원
• 'H(숫자)'및 '#'에 따른 숫자 크기 변환을 자율조절 가능하게 지원
• Visual Studio Code로 작성한 MarkDown을 pdf형식으로 저장 지원 => 현재 지원 가능(개선완료)
• 문서화된 파일 markdown 파일로 변환 현재 상용화된 https://github.com/jgm/pandoc/tree/master/src/Text/Pandoc
  이 오픈 소스는 word->md 넘어가면서 문법까진 인식이 안됨

Version Upgrade

• 18.12.15 docs-markdown(0.1.5)=>docs-markdown(0.2.1)

LICENSE

• MIT
• University of Illinois/NCSA Open Source License