우리의 MkDocs 연속
Source: Hacker News
소개
안녕하세요, MkDocs 커뮤니티 여러분!
저는 MkDocs의 이전(마지막 활동) 유지관리자로 알려져 있을 수도 있습니다.
MkDocs가 중단된 지점부터 이어지는 우리의 프로젝트 **ProperDocs**에 여러분 모두를 초대합니다. 이미 설치하여 MkDocs의 드롭‑인 대체제로 사용할 수 있습니다.
여러분의 도움이 필요합니다! 소식을 퍼뜨리고, 인사도 전하고, 관련 이슈를 우리에게 알려 주세요!
플러그인 제작자도 사용자에게 이 경고를 널리 알리는 데 도움을 줄 수 있습니다. (자세한 내용은 글 하단을 참고하세요)
왜 이것이 필요했는가
안타깝게도 현재 MkDocs는 완전히 관리되지 않고 있습니다. 원래 작성자는 지난 2 년 동안 프로젝트를 장악하고 있으며, 완전히 무시하고 모든 피드백과 들어오는 모든 이슈를 무시하고 있습니다. 유지 보수를 인수하겠다는 제안도 무시되었습니다. 또한 그들은 성별 선호도가 있다는 것을 공개적으로 밝히며, 모두를 매우 혼란스럽게 만들고 있습니다.
그들의 최신 계획은 프로젝트 이름을 재사용하고 그 아래 완전히 새로운 문서 생성기를 공개하는 것입니다. 이는 MkDocs용으로 만든 모든 테마와 플러그인에 대한 지원을 깨뜨리며, 대체 방안이 제공되지 않습니다. 커뮤니티 피드백도 환영받지 못하고 있습니다.
따라서 pip install mkdocs를 사용하면 이 파손이 언제 발생할지에 대한 지속적인 위험에 노출되는 것입니다.
사용자용 솔루션
우리는 여러분이 ProperDocs(MkDocs를 정성스럽게 포크한 버전)로 전환하시길 환영합니다. 현재 이것은 MkDocs와 정확히 동일하게 바로 교체해서 사용할 수 있으며, 몇 가지 중요한 버그 수정만 추가되었습니다. 향후 개발도 계획되어 있습니다.
Note
명령줄에서mkdocs를 실행할 때 나타나는 경고가 불편하다면, 환경 변수DISABLE_MKDOCS_2_WARNING=true또는NO_MKDOCS_2_WARNING=true를 설정하여 비활성화할 수 있습니다.
1. 의존성 교체
mkdocs를 의존성으로 사용하고 있다면, 다음과 같이 교체하세요:
# Before
pip install mkdocs mkdocs-foo-plugin
# After
pip install properdocs mkdocs-foo-plugin플러그인의 이름은 “mkdocs”가 포함되어 있더라도 그대로 유지됩니다. 플러그인은 변경 없이 작동하며, 플러그인 제작자는 프로젝트 이름을 바꿀 필요가 없습니다.
2. 명령어 교체
# Before
mkdocs build
# After
properdocs build명령줄은 완전히 동일하게 동작하며, 실행 파일 이름만 바뀝니다.
3. 선택적 후속 작업
프로그램이 이러한 사항을 알려주겠지만, 여기 다시 정리합니다:
mkdocs.yml파일명을properdocs.yml로 바꿀 수 있지만, 반드시 바꿀 필요는 없습니다.- 테마 “mkdocs” 또는 “readthedocs”를 사용한다면 별도로 설치해야 합니다. 이것이 유일한 호환성 깨짐이며, 현재 기본 테마는 제공되지 않습니다.
새로운 테마에 대한 기여를 특히 환영합니다.
기술 배경
포크가 실현 불가능하다고 오래전부터 믿어졌는데, 그 이유는 모든 플러그인이 mkdocs에 직접 의존하기 때문입니다. 나는 이러한 문제들을 극복할 수 있다는 것을 깨달았지만, 그 깨달음은 최근에야 떠올랐습니다.
플러그인 제작자를 위한 안내
우리는 모든 플러그인 제작자에게 우리의 노력에 동참해 줄 것을 요청합니다.
Note
우리는 MkDocs를 그대로 사용하고 있는 사용자들을 방해하도록 요구하지 않으며, ProperDocs만 작동하도록 마이그레이션할 필요도 없습니다. 여러분의 플러그인은 이미 MkDocs와 함께 ProperDocs에서도 정상적으로 동작합니다.
우리가 필요한 것은 소식을 널리 알리는 것입니다. 플러그인은 다음과 같이 도울 수 있습니다:
-
의존성을 수정하기:
# Change from mkdocs >=1.2.3 # to mkdocs >=1.2.3,