コンテンツ管理について

これは Braze Docs でのコンテンツ管理方法の概要です。特定のトピックについて詳しく知るには、ナビゲーションの専用トピックページを選択してください。

方法論

Braze Docsは、バージョン管理システムを使用してソフトウェア開発ライフサイクルを反映したドキュメントを管理する方法であるdocs-as-codeを使用して管理されます。Braze Docs は Git バージョン管理システムを使用しているため、寄稿者はお互いの作業を上書きすることなく、同じドキュメントを編集できます。詳細については、「バージョン管理と Git について」を参照してください。

サイトジェネレーター

Braze Docsは、コンテンツファイルとデザインファイルを別々のディレクトリに保存できる、人気の静的サイトジェネレーターであるJekyllを使用して構築されています。これにより、_docsコンテンツファイル用とデザインファイル用など、コンテンツファイルとデザインファイルを別々のディレクトリに保存できます。assetsサイトを構築すると、Jekyllは各ファイルをインテリジェントにマージし、XMLおよびHTMLデータとしてディレクトリに保存します。_site詳細については、「Jekyll ディレクトリ構造」を参照してください。

寄稿者は、主に以下のディレクトリで作業することになります。

ページ

Braze Docsの各ページはマークダウン構文で記述され、ファイル拡張子を使用してマークダウンファイルとして保存されます。.md各Markdownファイルの上部では、YAMLフロントマターを使用して各ページに非表示のメタデータを追加します。

```マークダウン

METADATA_KEY:METADATA_VALUE —

CONTENT

```

以下を置き換えてください。

• example input
• example output

画像

assets/img画像は内部にPNGファイルとして保存されます。imgディレクトリの構造は Braze Docs の構造と一致する必要はありませんが、関連する画像をサブディレクトリにまとめるのがベストです。

各画像は、次の構文を使用して1つまたは複数のページにリンクできます。

1
![ALT_TEXT.]({% image_buster /assets/img/DIRECTORY/IMAGE.png %})

以下を置き換えてください。

インライン画像は次のようになるはずです。

1
![The form for creating a new pull request on GitHub.]({% image_buster /assets/img/contributing/getting_started/github_pull_request.png %})

セクション

Braze Docs [は主要なセクションとサブセクションに分かれています](#primary-sections)。

主要セクション

Braze ドキュメントの主なセクションは以下のとおりです。

• Brazeドックスホーム
• ユーザーガイド
• 開発者ガイド
• Braze API ガイド
• テクノロジーパートナー
• Braze ヘルプ

これらの主要セクションには、Braze Docsのどのページからでもサイトヘッダーからアクセスできます。

各主要セクションはJekyllコレクションを使用して構築されているため、関連するコンテンツをグループ化して簡単に管理できます。すべてのプライマリセクションはコレクションですが、すべてのコレクションがプライマリセクションであるとは限らないことに注意してください。Braze Docs コレクションの全リストは Jekyll 設定ファイルにあります。_config.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
collections:
  home:
    title: Documentation
    output: true
    default_nav_url: ''
    page_order: 1
  user_guide:
    title: User Guide
    output: true
    default_nav_url: introduction/
    page_order: 2
  developer_guide:
    title: Developer Guide
    output: true
    default_nav_url: home/
    page_order: 3
  api:
    title: API
    output: true
    default_nav_url: home/
    page_order: 4
  partners:
    title: Technology Partners
    output: true
    default_nav_url: home/
    page_order: 5
  help:
    title: Help
    output: true
    default_nav_url: home/
    page_order: 6
  hidden: # Hidden pages not directly linked via navigation
    title: Braze
    output: true
    hidden: true
  docs_pages: # Site specific pages. ie main redirects and search
    title: Braze
    output: true
    hidden: true

リストされている各コレクションは、_docsディレクトリ内のディレクトリを表します。

1
2
3
4
5
6
7
8
9
10
braze-docs
└── _docs
    ├── _api
    ├── _developer_guide
    ├── _docs_pages
    ├── _help
    ├── _hidden
    ├── _home
    ├── _partners
    └── _user_guide

各主要セクションのランディングページは、page_order:0キーがに設定された標準のMarkdownファイルです。

• example input
• example output

サブセクション

Braze Docsのすべての主要セクションには1つ以上のサブセクションがあり、それぞれが左側のナビゲーションの展開可能な項目を表しています。

プライマリセクションとは異なり、サブセクションはランディングページの有無にかかわらず設定できます。ランディングページのないサブセクションは、Braze Docsの役に立たないページの数を最小限に抑えながら、関連するコンテンツをまとめて整理するのに役立ちます。サブセクションがランディングページの有無にかかわらず、すべてのサブセクションはリポジトリ内のディレクトリと Markdown ファイルの両方を表します。例については、以下を参照してください。

1
2
3
4
5
6
7
8
9
10
11
braze-docs
└── _docs
    └── _primary_section
        ├── subsection_a
        │   ├── page_a.md
        │   └── page_b.md
        ├── subsection_b
        │   ├── page_a.md
        │   └── page_b.md
        ├── subsection_a.md # not configured as a landing page
        └── subsection_b.md # configured as a landing page  

_primary_sectionディレクトリでは、subsection_aはランディングページで構成されていませんがsubsection_b、にはランディングページが設定されています。次の例では、subsection_a.mdconfig_only:がに設定されています。これによりtrue、このページはランディングページとしてレンダリングされません。

• example input
• example output

ただし、subsection_b.mdconfig_only:キーを使用しないため、このページはランディングページとしてレンダリングされます。

• example input
• example output

コンテンツ再利用

Jekyllには、タグを使用して書かれたコンテンツをドキュメント全体で再利用する機能があります。include_includesインクルードはディレクトリにあり、MarkdownまたはHTML構文で記述できます。

1
{% multi_lang_include RELATIVE_PATH/FILE %}

以下を置き換えてください。

• example input
• example output

レイアウト

デフォルトでは、default.html _layouts Jekyllはディレクトリ内のレイアウトを使用してBraze Docsの各ページを作成します。ただし、YAML layout: フロントマターのキーにレイアウトを割り当てることで、さまざまなレイアウトを使用できます。

```マークダウン

layout: レイアウト値 — ```

レイアウトファイルの名前とファイル拡張子を削除した名前に置き換えますLAYOUT_VALUE。

• example input
• example output

1
2
3
braze-docs
└── _layouts
    └── api_page.html

URL

Braze Docs の URL は、常にドキュメントリポジトリ内のディレクトリ構造と一致します。次のファイルツリーの例を考えると、の URL page_a.md はになりますhttps://www.braze.com/docs/primary_section/subsection_a/page_a。

1
2
3
4
5
braze-docs
└── _docs
    └── _primary_section
        └── subsection_a
            └── page_a.md

これには、config_only:がに設定されているサブセクションにあるページの URL が含まれます。trueconfig_onlyサブセクションはページとしてレンダリングされませんが、サブセクションのディレクトリ名は、そのディレクトリ内のページの URL を生成するために引き続き使用されます。例については、以下を参照してください。

1
2
3
4
5
6
7
8
9
10
11
braze-docs
└── _docs
    └── _primary_section
        ├── subsection_a
        │   ├── page_a.md
        │   └── page_b.md
        ├── subsection_b
        │   ├── page_a.md
        │   └── page_b.md
        ├── subsection_a.md # not configured as a landing page
        └── subsection_b.md # configured as a landing page  

• subsection a
• subsection b

1
2
3
Subsection A URL: N/A
Page A URL: https://www.braze.com/docs/primary_section/subsection_a/page_a
Page B URL: https://www.braze.com/docs/primary_section/subsection_a/page_b

1
2
3
Subesction B URL: https://www.braze.com/docs/primary_section/subsection_b
Page A URL: https://www.braze.com/docs/primary_section/subsection_b/page_a
Page B URL: https://www.braze.com/docs/primary_section/subsection_b/page_b