자신의 Git 리포지토리에서 Readme.io 문서 사이트의 콘텐츠를 관리합니다.

This article originally appeared on my personal dev blog.

ReadMe.io은 인기 있는 사용자 문서 사이트입니다. Markdown 편집기, 테마 빌더 및 Swagger/OpenAPI 파일 가져오기가 있습니다. 빠르고 반응이 좋으며 멋져 보입니다. 하지만 마지막으로 확인했을 때 모든 콘텐츠는 직접 액세스할 수 없는 버킷으로 이동합니다.

이것의 한 가지 결론은 제품 이름 변경과 같이 문서 전체를 변경하려는 경우 문서를 개별적으로 편집해야 한다는 것입니다. VS Code에서 리포지토리에 직접 액세스하여 사이트 전체를 변경할 수 있다면 훨씬 더 좋을 것입니다.

이것이 지원되지 않더라도 Readme.io에는 데이터를 제어할 수 있는 몇 가지 기능이 있습니다. 먼저 export your content . 둘째, Readme.io에는 API . 웹 인터페이스에서 여전히 수행해야 하는 몇 가지 작업이 있습니다. 그러나 대부분의 경우 데이터를 Git 리포지토리에 보관하고, 로컬에서 변경하고, API를 사용하여 변경 사항을 라이브 사이트에 푸시할 수 있습니다.

ReadMe.io API

시작할 때 Postman을 사용하여 Readme.io 사이트를 쿼리하는 것이 유용하다는 것을 알았습니다. 이 컬렉션을 readme.postman_collection.json로 저장할 수 있습니다.

{
"info": {
"_postman_id": "<!--insert your postman ID here-->",
"name": "readme.io",
"schema": "[https://schema.getpostman.com/json/collection/v2.1.0/collection.json](https://schema.getpostman.com/json/collection/v2.1.0/collection.json "https://schema.getpostman.com/json/collection/v2.1.0/collection.json")"
},
"item": \[
{
"name": "Get doc",
"request": {
"method": "GET",
"header": \[\],
"url": {
"raw": "[https://dash.readme.com/api/v1/docs/](https://dash.readme.com/api/v1/docs/ "https://dash.readme.com/api/v1/docs/"){{slug}}",
"protocol": "https",
"host": \[
"dash",
"readme",
"com"
\],
"path": \[
"api",
"v1",
"docs",
"{{slug}}"
\]
}
},
"response": \[\]
},
{
"name": "Get category ID",
"request": {
"method": "GET",
"header": \[\],
"url": {
"raw": "[https://dash.readme.com/api/v1/docs/get-category-id](https://dash.readme.com/api/v1/docs/get-category-id "https://dash.readme.com/api/v1/docs/get-category-id")",
"protocol": "https",
"host": \[
"dash",
"readme",
"com"
\],
"path": \[
"api",
"v1",
"docs",
"get-category-id"
\]
}
},
"response": \[\]
},
{
"name": "Update doc",
"request": {
"method": "PUT",
"header": \[\],
"body": {
"mode": "raw",
"raw": "{\\n \\"title\\": \\"{{title}}\\",\\n \\"excerpt\\": \\"{{excerpt}}\\",\\n \\"category\\": \\"{{category}}\\",\\n \\"hidden\\": {{hidden}},\\n \\"body\\": \\"{{body}}\\"\\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "[https://dash.readme.com/api/v1/docs/](https://dash.readme.com/api/v1/docs/ "https://dash.readme.com/api/v1/docs/"){{slug}}",
"protocol": "https",
"host": \[
"dash",
"readme",
"com"
\],
"path": \[
"api",
"v1",
"docs",
"{{slug}}"
\]
}
},
"response": \[\]
},
{
"name": "Delete doc",
"request": {
"method": "DELETE",
"header": \[\],
"url": {
"raw": "[https://dash.readme.com/api/v1/docs/](https://dash.readme.com/api/v1/docs/ "https://dash.readme.com/api/v1/docs/"){{slug}}",
"protocol": "https",
"host": \[
"dash",
"readme",
"com"
\],
"path": \[
"api",
"v1",
"docs",
"{{slug}}"
\]
}
},
"response": \[\]
},
{
"name": "Create doc",
"request": {
"method": "POST",
"header": \[\],
"body": {
"mode": "raw",
"raw": "{\\n \\"title\\": \\"{{title}}\\",\\n \\"excerpt\\": \\"{{excerpt}}\\",\\n \\"category\\": \\"{{category}}\\",\\n \\"hidden\\": true,\\n \\"body\\": \\"{{body}}\\"\\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "[https://dash.readme.com/api/v1/docs](https://dash.readme.com/api/v1/docs "https://dash.readme.com/api/v1/docs")",
"protocol": "https",
"host": \[
"dash",
"readme",
"com"
\],
"path": \[
"api",
"v1",
"docs"
\]
}
},
"response": \[\]
},
{
"name": "Search docs",
"request": {
"method": "POST",
"header": \[\],
"url": {
"raw": "[https://dash.readme.com/api/v1/docs/search?search=sphinx](https://dash.readme.com/api/v1/docs/search?search=sphinx "https://dash.readme.com/api/v1/docs/search?search=sphinx")",
"protocol": "https",
"host": \[
"dash",
"readme",
"com"
\],
"path": \[
"api",
"v1",
"docs",
"search"
\],
"query": \[
{
"key": "search",
"value": "sphinx"
}
\]
}
},
"response": \[\]
}
\],
"auth": {
"type": "basic",
"basic": \[
{
"key": "username",
"value": "{{apiKey}}",
"type": "string"
}
\]
},
"event": \[
{
"listen": "prerequest",
"script": {
"type": "text/javascript",
"exec": \[
""
\]
}
},
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": \[
""
\]
}
}
\],
"variable": \[
{
"key": "category\\n",
"value": "<!--get the category ID from the web interface-->"
},
{
"key": "slug",
"value": "sandbox"
},
{
"key": "title",
"value": "Sandbox"
},
{
"key": "hidden",
"value": "true"
},
{
"key": "body",
"value": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
}
\]
}

컬렉션을 Postman으로 가져오고 API 키를 사용자 이름으로 사용하고 빈 비밀번호로 기본 인증을 사용합니다.


문서 만들기

이 엔드포인트에는 다음 속성이 필요합니다.

제목 – 사이트에 표시할 이름입니다.

범주 – UUID

숨김 - 거짓

본문 - JSON 문자열

hidden 속성은 항상 true 로 설정됩니다. 콘텐츠가 표시되는 대로 검토한 후 최종 게시 단계는 이것을 false 로 설정하는 것입니다.

제가 놓친 것이 없다면, 처음 이 솔루션을 생각해냈을 때 Readme.io에서만 카테고리를 만들 수 있었습니다. 그러나 that 에 대한 API가 있습니다. 현재 테스트할 활성 Readme.io 구독이 없으므로 해당 끝점을 Postman 컬렉션에 추가하는 것은 사용자에게 맡기겠습니다.

기사는 기존 기사 아래에 게시할 수 있습니다. 이 경우 상위 기사에서 GET를 수행하여 카테고리 ID를 가져와야 합니다.

JQ를 사용하여 Markdown을 JSON 문자열로 변환

Readme.io는 기사를 Markdown 형식(YAML 헤더 포함)으로 저장합니다. 그러나 API에는 JSON 형식의 데이터가 필요합니다. 다행스럽게도 Markdown을 JSON 문자열로 캡슐화할 수 있는 명령줄 도구 호출JQ이 있습니다. 그러면 body 속성이 형성됩니다. CLI에서 다음을 입력합니다. jq -R -s . < filename.md > filename.txt .

리포지토리의 변경 사항을 라이브 사이트로 푸시

.md 메서드를 사용하여 리포지토리의 모든 PUT 파일을 자동으로 업데이트하는 Bash 스크립트를 작성했습니다. 약간의 해킹입니다. $AUTH 토큰을 정의해야 하며 헤더가 정확히 8줄인 파일에서만 작동합니다.

---
title: "article title"
category: "category UUID"
excerpt: "article description"
hidden: true
createdAt: "2022-05-19T00:00:00.000Z"
updatedAt: "2022-05-19T10:00:00.001Z"
---

기본적으로 Readme.io에서 다운로드하는 기사에는 메타데이터가 포함되지만slug 메타데이터는 포함되지 않습니다category. 슬러그는 파일 이름에서 파생되므로 slug 메타데이터를 category 메타데이터로 교체하고 아래에 표시되는 카테고리 제목에 적합한 UUID를 제공해야 합니다.

참고: excerpt 정의를 포함하지 않는 경우 body 텍스트가 파일의 라인9에서 시작하는지 확인해야 합니다.

다음은 Bash 스크립트입니다. 내보낸 사이트의 md2json.sh 폴더에 v1.0로 저장합니다.

export AUTH="<!--your AUTH token-->"
for subdir in *; do
test -d "$subdir" || continue
echo $subdir
cd "$subdir"
for f in _.md; do
export SLUG=${f%%._}
sed '1,8d' $f > "$SLUG.tmp"
sed '6,$d' $f > "$SLUG.yml"
jq -R -s . < "$SLUG.tmp" > "$SLUG.bdy"
rm "$SLUG.tmp"
printf "body: " >> "$SLUG.yml"
cat "$SLUG.bdy" >> "$SLUG.yml"
yq < "$SLUG.yml" > "$SLUG.json"
rm "$SLUG.bdy"
rm "$SLUG.yml"
curl -X PUT -H 'Content-Type: application/json'   
\-H "Authorization: Basic $AUTH"   
\-d "$(<$SLUG.json)"   
https://dash.readme.com/api/v1/docs/$SLUG
rm "$SLUG.json"
done
cd ..
done

이미지 관리

퍼즐의 마지막 부분은 이미지 관리입니다. 글을 쓰는 시점에서 API를 사용하여 이미지를 업로드하는 방법을 모르겠습니다. 내 제안은 웹사이트에 숨겨진 기사를 유지하고 웹 인터페이스를 사용하여 이미지를 추가하는 것입니다. Readme.io는 파일 이름을 바꾸고 ID를 할당합니다. 그런 다음 기사에서 이 정보를 추출할 수 있습니다. 그런 다음 이 수정된 파일 이름이 있는 이미지 사본을 리포지토리에 추가합니다(다른 문서 솔루션으로 마이그레이션하려는 경우). 이렇게 하면 콘텐츠를 라이브 사이트로 푸시하기 전에 로컬에서 미리 볼 수도 있습니다.