【最新サービス試用⑥】簡単にドキュメントやポートフォリオを作成できるサイト作成ツールの「Docusaurus」を試用

14263 ワード
React JavaScript Docusaurus 初心者 Markdown JavaScript テキストリンク
  • 日々輩出される素晴らしき最新サービスを素早く試して、不鮮明な先見性を堂々と誇示する記事第六弾。
  • 幾度となく、「最先端」「自動生成」というサービスに一目散に飛びついてきた生活は、元号変化の新時代も継続。
  • 今回は、マークダウン形式で簡単にドキュメントやブログを作成できるジェネレータの「Docusaurus」を試用することにしよう。

目的とゴール

  • Docusaurusの概要や特徴の把握
  • 類似サービスの把握
  • Docusaurusの導入方法の把握
  • プロジェクトの作成方法の把握
  • サーバーの起動方法の把握
  • 新規ページの作成方法の把握
  • 様々なマークダウン形式の表示確認
  • ※今回はデプロイやCIツールとの連携は行わない

概要

  • Docusaurusは、Facebook開発のドキュメント作成ジェネレーター。
  • マークダウンを用いて、簡単にドキュメントを作成できるため、主にオープンソースプロジェクトのドキュメント生成用として使われている。
  • 公開やCIツールとの連携が容易であるため、ポートフォリオサイト作成としても使われている。
  • 公式サイト

特徴

マークダウン形式でのドキュメント記述

  • ドキュメントやコンテンツをマークダウンで記述することができ、自動でページやHTMLファイルを出力してくれる。
  • シンタックスハイライトやテーブル等、様々なマークダウン形式に対応している。

Reactを用いた記述

  • レイアウトの拡張やカスタマイズを、Reactで記述することができる。

翻訳機能対応

  • Crowdinという翻訳サービスとの連携で、簡単にドキュメントの多言語対応が実装できる。

検索機能対応

  • DocSearchという検索サービスとの連携で、簡単にドキュメントの文章検索機能を実装できる。

バージョニング

  • ドキュメントが古くなっても、最新の内容に基づいて、最適なバージョン管理を行うことができる。

サイト公開とCI連携の容易さ

  • ホスティングサービスであるNetlifyやGitHub Pagesを利用して、簡単にサイトを公開することができる。
  • また、CircleCIやTravisCI等の、CIツールとの連携にも対応

類似サービス

手順

環境

  • Mac OS X 10.13.4Mac OS X 10.13.4
  • NodeJs v11.6.0

導入

  • ターミナル(コマンドプロンプト)を開き、下記のコマンドをうち、Docusaurusを導入する。
    • ※Nodejsが入っていない場合、インストールする。 
$ npm install --global docusaurus-init

プロジェクト作成

  • 下記のコマンドをうち、Docusaurus新規プロジェクトを作成する。
# プロジェクトフォルダの作成
$ mkdir ~/docsaurus_sample
# プロジェクトフォルダへ移動
$ cd ~/docsaurus_sample
# Docusaurus新規プロジェクトの作成
$ docusaurus-init

構成

  • docusaurus-initコマンドで作成されたプロジェクトは、下記のような構成になっている。
root
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   ├── exampledoc4.md
│   └── exampledoc5.md
└── website
    ├── blog
    │   ├── 2016-03-11-blog-post.md
    │   ├── 2017-04-10-blog-post-two.md
    │   ├── 2017-09-25-testing-rss.md
    │   ├── 2017-09-26-adding-rss.md
    │   └── 2017-10-24-new-version-1.0.0.md
    ├── core
    │   └── Footer.js
    ├── package.json
    ├── pages
    ├── sidebars.json
    ├── siteConfig.js
    └── static
  • 主に下記の内容で、適切なファイルを配置していく
    • docs/・・・ドキュメントのMarkdownファイルを配置していく。
    • website/blog・・・ブログ用記事の配置していく。
    • website/pages・・・通常ページファイルを配置していく。
    • website/static・・・サイトの画像やスタイルを配置していく。

チュートリアルページ確認

  • 下記のコマンドをうち、ローカルサーバーを起動する。
# websiteフォルダへ移動
$ cd ~/docsaurus_sample/website
# ローカルサーバー起動
$ npm start

新規ページ作成

1. ドキュメントページ作成

  • docs/配下に、.md形式でファイルを新規作成して、配置する。
    • 今回は、サンプルとして、intro.mdとして作成する。
  • intro.mdの中身を下記にする。
    • ※シンタックスハイライト部分の「\」は不要。
intro.md
---
id: intro
title: t_o_d on intro
---

# タイトルテスト

## サブタイトルテスト

### 本文テスト

- 本文テスト

### ネストテスト

- 本文テスト
    - ネストテスト

### 書式等テスト

- **太字テスト**
- ~~打消し線テスト~~
- <details><summary>折りたたみテスト</summary>折りたたまれているようだ</details>
- > 引用テスト

### 水平線テスト

- 水平線テスト
---

### 画像テスト

![penguin](https://user-images.githubusercontent.com/44114228/57018373-3eedac80-6c5e-11e9-91e8-2d5ce7d418ac.png)

### シンタックスハイライトテスト

\```ruby
# テスト
puts "Hello t_o_d"
\```

### テーブルテスト

|タイトル|内容|
|:---:|:---:|
|イントロ|テスト|

### リンクテスト

- [リンク](https://www.google.co.jp/)
  • 中身を記述後、website\sidebars.jsonに作成したファイルを、下記のように追加する。
sidebar.json
{
  "docs": {
    "Docusaurus": ["doc1"],
    "First Category": ["doc2"],
    "Second Category": ["doc3"],
    "Intro": ["intro"]
  },
  "docs-other": {
    "First Category": ["doc4", "doc5"]
  }
}
  • 中身を記述後、http://localhost:3000/docs/intro にアクセスして、下記の画面が表示されることを確認する。
    • ※アクセスできない場合、ローカルサーバーをCtrl + Cで終了して、再度npm startで起動する。


2. 通常ページ作成

  • website\pages\en\配下に、.js形式でファイルを新規作成して、配置する。
    • 今回は、サンプルとして、test.jsとして作成する。
  • test.jsの中身を、既存のindex.jsを少し変えて、下記のようにする。
    • ※.jsの中身はReact記法で書くことができる。
test.js
const React = require('react');

const CompLibrary = require('../../core/CompLibrary.js');

const Container = CompLibrary.Container;

function Test(props) {
    return (
        <div className="docMainWrapper wrapper">
            <Container className="mainContainer documentContainer postContainer">
                <h1>Hello t_o_d</h1>
                <p>I am t_o_d</p>
            </Container>
        </div>
    );
}

module.exports = Test;
  • 記述して保存後、http://localhost:3000/test にアクセスして、下記の画面が表示されることを確認する。

まとめ

  • 今回は、サイト生成ジェネレーターの試用ということで、日々増殖を続ける自動生成ツールの恩恵を際限なくいただきながら、記事を書く。
  • 「OSSプロジェクトのドキュメント用だが、技術記事やポートフォリオとしても利用できそう」という、主目的の「OSS」の高権威専用用語から、全力で逃避を図ろうとする。
  • 「試用ということで使ってみたが、検索機能や翻訳機能、CI連携等も確かめてみよう」という、今後の目標を確定した直後に、次なる豊かな最新サービスを探す迷走生活。

参考