このサイトのHTML構成

Created 2022-02-06, Modified 2022-02-20.

概要

この記事はこのサイトの記事の構成方法やHTML部品をまとめている. 自力でちまちま書いているHTMLコードのちょっとした覚書のようなものだ.

私は記事を直接HTML記述で作成している[*1]. 私はタグ打ち行為にさほど抵抗感がないし, タグの不一致や記述ミスはエディタの力で十分対処可能な範疇だと思っている. 管理ツールもない. 数100から数1000ページを取り扱う管理ツールは少なくとも今はまだ必要でない.[*2]

コード構成

基本コンセプト

シンプルであること
論文をイメージした2段組であること
jsに頼りすぎない

基本HTML構成

HTMLのbody配下は次のように並ぶ. ここにあるidはCSSでも利用するレベルでただ一つの共通項である. #contentの配下はさらにReality側とFiction側で分かれる.

#logo :: ロゴ
#site-sign :: 標識, 色で区別
- #this-sign :: Reality側, peru
- #other-sign :: Fiction側, blueviolet
#search :: サイト内検索
#toc :: ページ内目次. よほど大きくないと利用しない
#content :: 文章本体. 2段組はこれにかかる
footer :: 今のところ空っぽ

Reality側の#content基本構成

タイトルと作成日, 変更日, 諸注意
概要や結果などのこの記事を読むべきかどうかの判断材料の提供
語句定義
本文
参考
脚注やライセンス表記

Fiction側の#content基本構成

タイトルと作成日, 変更日, 諸注意
本文
脚注
ライセンス表記

他注意事項チェックリスト

headerのmetaタグの自身へのリンク記述
headerのmetaタグの自身の説明記述
外部参照aタグへrel="nofollow noopener" target="_blank"を付与
indexの更新
積極的な脚注の利用("できるだけより多く"を語っている状態を善とする)
kb(記事サイズ)と記事の質に相関関係はない
出し惜しみしない

HTML部品

ロゴ

bodyタグ直下に次を配置.

          <header><div id="logo" class="od-center"><a class="logo-link xxx-large bolder rev-color" href="/index.html"><span>Ready </span><span class="italy">one</span><span>self ...</span></a></div></header>

標識と検索

          <nav id="site-sign">
            <img id="this-sign" src="/image/site-sign.svg" width="2em" height="2em" alt="" />
            <form id="search" method="post" action="https://www.google.co.jp/search">
              <input id="site-search" title="Search the site" type="search" name="q" size="35" maxlength="255" value="" />
              <input type="submit" value="Search" />
              <input type="hidden" name="q" value="site:ready-oneself.net" />
            </form>
          </nav>

          <nav id="toc">
            <h1 class="od-center pierce">Table of Contents.</h1>
            <ul>
            </ul>
          </nav>

#content開始あたり

単一記事を扱うならarticleを利用し, そうでないときはdivで置き換え.

          <article id="content">
            <header class="pierce">
              <h1 class="od-center">タイトル</h1>
              <p class="smaller od-right">Created <time>2022-</time>, Modified <time>2022-</time>.</p>
              <p class="smaller"><!-- 諸注意 --></p>
            </header>
          
            <!-- 章レベルブロック -->
          
          </article>

章レベルブロック

#content開始直後では概ね次の形となる. そうでないときの図表系のブロックではmainをsectionにして, classをjointのみにする. 脚注はclassにfootnoteを与える.

          <main class="pierce narrow joint">
            <h2>概要, 結果, 成果物</h2>
            <p></p>
            <figure><!-- 図表, コード, 引用を参照 --></figure>
          </main>

より汎化したブロック構成が次.

          <section class="joint">
            <h2>章</h2>
            <p></p>
          </section>

図表, コード, 引用

figureを利用する. 表, リスト, コード, 引用はfigcaptionを上に, 図はfigcaptionを下につける.

種別は今のところ, Fig, Table, List, Code, Citeの5種.

          <figure>
            <figcaption>
              <p class="italy" id="_list-1">List 1. リストX</p>
            </figcaption>
            <ul>
              <li>X-1</li>
              <li>X-2</li>
            </ul>
          </figure>

          <figure>
            <figcaption><p class="italy od-center" id="_cite-1">Cite 1. <cite><a href="url" rel="nofollow">引用ページタイトル</a> </cite>(<time>引用年月日</time>)</p></figcaption>
            <blockquote cite="url">
              <p>引用内容</p>
              <pre>
                <code>コード</code>
              </pre>
              <p>(略)</p>
            </blockquote>
          </figure>

語句定義

dtの中はspanで文字装飾を行う. ddの個数は各dtで揃える. また, 語句の説明程度であるならば, dtの強調効果はなくても良い.

          <h3>語句定義</h3>
          <dl class="atomic">
            <dt><span class="bolder">定義語</span></dt>
            <dd><p>意味</p></dd>
          </dl>

脚注, リンク, 書籍

脚注記号は'*'を正規とする. しかし, 作品内脚注として'&'を用いることもある.

          <a class="smaller" href="#_fn1">[*1]</a>
          <p id="_fn1">*1 :: .</p>

書籍引用元表記は著者, 本の題名, 発行年, 発行団体, 引用ページ...をできるだけ守る.

カードスタイル

          <div class="card">
            <section class="card-content" style="局所的なスタイル設定">
              <h2 class="card-title" style="必要ない時は display: none;">見出し</h2>
              <p class="card-text"><!-- カードタイプではあまり長い文章を想定していない --></p>
            </section>
          </div>

折りたたみ

          <details>
            <summary>折りたたみ</summary>
            <p></p>
          </details>

文章および文字効果

classに装飾子をつけて行う.

atomic: ブロック中の改段抑制
pierce: 段組みの横方向ぶち抜き
od-center: 文章中央揃え
od-right: 文章右揃え
larger: 文字の相対拡大
smaller: 文字の相対縮小
xxx-large: 文字の3.5倍拡大
italy: イタリック体
bolder: 太字

エスケープ文字列作成

'<', '>', '&'のエスケープにはtemp.txtに対象コードを一時的に保存して, 次のsedをかける.

          sed -e 's/&/\&/g' -e 's/>/\>/g' -e 's/</\</g' temp.txt

さらに対象を<code></code>で包むなら, 次のsedにパイプで繋ぐ.

          sed -e 's:^\([ ]*\)\([^ ].*\)$:\1<code>\2</code>:g'

*1 :: 当初から中期にかけてはMarkdownやAsciidocからの自動生成をしようとしていた. しかし, それによって出力されるHTMLは余計な効果装飾が多く, 納得ができなかった. 他の変換方法(Emacs org, sphinx, latex)でも私には過剰だった. よって, もういっそ自力でコーディングしたほうが早いとなってしまった.

*2 :: ページ描画の高速化は達成してみたい. 私はこれをscriptやajaxの利用を最小限にすることで狙う.