閉じる

WordPress関数 the_permalink の使い方：記事URLの出力方法とテンプレートでの活用術

広告

WordPressで動的なWebサイトを構築する際、個々の記事や固定ページへのリンクを自動的に生成することは非常に重要な要素です。

そこで欠かせないのが、WordPressのテンプレートタグの一つであるthe_permalink()です。

この関数を正しく理解し、適切に使い分けることで、メンテナンス性の高い効率的なテーマ開発が可能になります。

本記事では、初心者から中級者の開発者に向けて、the_permalink()の基本的な使い方から実戦的な応用術、さらには類似関数との違いまでを詳しく解説します。

目次 [ close ]
  1. the_permalink 関数とは
    1. 主な用途
  2. the_permalink の基本的な使い方
    1. 基本的な記述例
  3. the_permalink と get_permalink の違い
    1. 比較表
    2. get_permalink の使用例
  4. テンプレートファイルでの活用術
    1. 1. 記事一覧での「続きを読む」ボタン
    2. 2. サムネイル画像（アイキャッチ）へのリンク
    3. 3. ループ外で特定の記事URLを取得する
  5. カスタムクエリ（WP_Query）での活用術
  6. パーマリンク構造とSEOへの影響
    1. 推奨される設定
  7. よくあるトラブルと対処法
    1. 1. URLが正しく表示されない、または404エラーになる
    2. 2. ループの外で期待しないURLが出力される
    3. 3. URLに余計な文字列が含まれる
  8. 2026年におけるパーマリンク運用の注意点
  9. まとめ

the_permalink()は、現在処理されている投稿（ループ内の投稿）のパーマリンク（個別記事のURL）を表示するためのWordPress専用のテンプレートタグです。

WordPressの管理画面で設定した「パーマリンク設定」に基づいた正しいURLを動的に出力してくれます。

この関数の最大の特徴は、関数自体が「URLをエコー（echo）する」機能を持っている点です。

そのため、PHPのecho文を記述することなく、関数を呼び出すだけでその場にURLを書き出すことができます。

主な用途

主な用途としては、以下のような場面が挙げられます。

  • 記事一覧ページ（index.php や archive.php）で、各記事のタイトルに詳細ページへのリンクを貼る。
  • 「続きを読む」ボタンのリンク先として設定する。
  • ソーシャルメディアのシェアボタンのリンク先としてURLを埋め込む。

the_permalink()は、原則として「WordPressループ（The Loop）」の中で使用します。

ループとは、データベースから取得した投稿情報を順番に処理するための仕組みのことです。

基本的な記述例

最も標準的な使い方は、HTMLの<a>タグのhref属性の中に記述する方法です。

PHP
<?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <!-- 記事のタイトルにパーマリンクを設定する例 -->
        <h2>
            <a href="<?php the_permalink(); ?>">
                <?php the_title(); ?>
            </a>
        </h2>
    <?php endwhile; ?>
<?php endif; ?>

上記のコードが実行されると、ブラウザ上には以下のようなHTMLが出力されます。

HTML
<h2>
    <a href="https://example.com/2026/05/hello-world/">
        Hello world!
    </a>
</h2>

このように、WordPressが自動的に各記事のIDを判別し、正しいURLを生成してくれます。

開発者が手動でURLを入力する必要がないため、サイトのドメイン変更やパーマリンク構造の変更があった場合でも、リンク切れを起こす心配がありません。

WordPressには、よく似た名前の関数としてget_permalink()が存在します。

これら2つの関数の決定的な違いは、「値をそのまま出力するか、戻り値として返すか」という点にあります。

比較表

関数名出力の有無主な用途引数の指定
the_permalink()あり（echoされる）テンプレート内で直接URLを表示する際原則不要（ループ内）
get_permalink()なし（returnされる）変数に代入したり、PHPで加工したりする際投稿IDなどの指定が可能

値を加工したい場合や、条件分岐に使いたい場合はget_permalink()を使用します。

PHP
<?php
// URLを変数に代入する
$post_url = get_permalink();

// URLに特定の文字列が含まれているかチェックする例
if ( strpos( $post_url, 'special-topic' ) !== false ) {
    echo '<p>これは特集記事です。</p>';
}

// 属性として安全に出力するために esc_url を併用するのが一般的
echo '<a href="' . esc_url( $post_url ) . '">リンクはこちら</a>';
?>

the_permalink()は内部的にget_permalink()を呼び出していますが、最終的な出力時にはthe_permalinkというフィルターフックを通るという特徴もあります。

基本的には、「表示するだけなら the_ 、データとして扱うなら get_ 」と覚えておけば間違いありません。

テンプレートファイルでの活用術

実際のテーマ制作において、どのように活用されるのか、より具体的なケースを見ていきましょう。

1. 記事一覧での「続きを読む」ボタン

多くのブログ形式のサイトでは、記事の抜粋を表示した後に詳細ページへ誘導するボタンを設置します。

PHP
<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
    <header class="entry-header">
        <?php the_title( '<h1 class="entry-title">', '</h1>' ); ?>
    </header>

    <div class="entry-summary">
        <?php the_excerpt(); ?>
    </div>

    <footer class="entry-footer">
        <!-- class属性を指定してボタン風のデザインにする -->
        <a href="<?php the_permalink(); ?>" class="read-more-button">
            この記事の続きを読む
        </a>
    </footer>
</article>

2. サムネイル画像（アイキャッチ）へのリンク

画像をクリックした際に記事詳細ページへ飛ばしたい場合も、同様の手法が使えます。

PHP
<?php if ( has_post_thumbnail() ) : ?>
    <div class="post-thumbnail">
        <a href="<?php the_permalink(); ?>">
            <?php the_post_thumbnail( 'medium' ); ?>
        </a>
    </div>
<?php endif; ?>

3. ループ外で特定の記事URLを取得する

特定の固定ページや、おすすめ記事として指定したIDのURLを取得したい場合は、get_permalink()に投稿IDを渡します。

PHP
<?php
// IDが 123 の投稿URLを取得して表示する
$specific_post_id = 123;
$url = get_permalink( $specific_post_id );
?>

<a href="<?php echo esc_url( $url ); ?>">特定のおすすめ記事へ</a>

カスタムクエリ（WP_Query）での活用術

メインループ以外で記事一覧を表示する場合（例えばサイドバーの最新記事リストや、関連記事一覧など）でも、the_permalink()は非常に役立ちます。

PHP
<?php
$args = array(
    'posts_per_page' => 5,
    'category_name'  => 'news',
);
$news_query = new WP_Query( $args );

if ( $news_query->have_posts() ) :
    echo '<ul>';
    while ( $news_query->have_posts() ) : $news_query->the_post();
        ?>
        <li>
            <span class="date"><?php echo get_the_date(); ?></span>
            <a href="<?php the_permalink(); ?>">
                <?php the_title(); ?>
            </a>
        </li>
        <?php
    endwhile;
    echo '</ul>';
    // グローバル変数のリセットを忘れずに行う
    wp_reset_postdata();
endif;
?>

ここで重要なのは、$news_query->the_post()を呼び出すことで、グローバル変数の$postが更新される点です。

これにより、the_permalink()が現在処理中のサブループ内の投稿URLを正しく認識できるようになります。

パーマリンク構造とSEOへの影響

the_permalink()がどのようなURLを出力するかは、WordPress管理画面の「設定 > パーマリンク設定」に依存します。

推奨される設定

2026年現在のWeb標準においても、SEOの観点から「意味のある単語を含んだシンプルなURL」が推奨されています。

  • 基本（非推奨）: https://example.com/?p=123
  • 投稿名（推奨）: https://example.com/sample-post/
  • 数字ベース: https://example.com/archives/123

the_permalink()を使用していれば、管理画面で設定を「基本」から「投稿名」に変更したとしても、テーマ側のコードを書き換える必要は一切ありません。WordPressが内部で自動的にマッピングを更新し、新しい構造のURLを出力してくれるからです。

これが、絶対パスでURLを直書きしてはいけない最大の理由です。

よくあるトラブルと対処法

1. URLが正しく表示されない、または404エラーになる

パーマリンク設定を変更した直後などに、リンク先が404エラーになることがあります。

これはWordPressの「リライトルール」が更新されていないことが原因であることが多いです。

  • 対処法: 管理画面の「設定 > パーマリンク設定」を開き、何も変更せずに「変更を保存」ボタンをクリックしてください。これによりリライトルールが強制的に更新され、正しいURLでアクセスできるようになります。

2. ループの外で期待しないURLが出力される

the_permalink()をループの外（例えば header.php や footer.php）で使用すると、予期しない記事のURLが出力されたり、あるいは何も出力されなかったりすることがあります。

  • 対処法: ループ外で特定のページのURLを取得したい場合は、前述の通りget_permalink( $post_id )を使用して、明示的にIDを指定するようにしましょう。

3. URLに余計な文字列が含まれる

プラグインの影響などで、URLの末尾に意図しないパラメータが付与されることがあります。

  • 対処法: the_permalink フィルターフックを使用して、出力される直前のURLをカスタマイズすることが可能です。 functions.php に以下のようなコードを記述することで制御できます。
PHP
function custom_permalink_handler( $url ) {
    // 必要に応じてURLを加工する処理
    return $url;
}
add_filter( 'the_permalink', 'custom_permalink_handler' );

2026年におけるパーマリンク運用の注意点

近年のWordPressでは、ブロックテーマ（フルサイト編集：FSE）の普及により、PHPファイルを直接編集する機会は減少傾向にあります。

しかし、クエリーループブロックの内部的な挙動や、カスタムブロックの開発においては、依然としてthe_permalink()の仕組みを理解しておくことが不可欠です。

特に、ヘッドレスWordPress（フロントエンドにReactやNext.jsを使用する構成）を採用する場合、PHPのthe_permalink()を直接使うことはありませんが、REST API経由で取得されるlinkプロパティが、この関数の出力結果に相当します。

基盤となるWordPress側でパーマリンク設定が正しく行われていなければ、API経由でも正しいURLは取得できません。

また、セキュリティ（エスケープ処理）についても意識を向けるべきです。

the_permalink()自体はWordPressによってある程度安全に処理されていますが、URLを属性値として扱う性質上、常に最新のパッチが適用された環境で運用することが推奨されます。

まとめ

the_permalink()は、WordPressテーマ開発における「もっとも基本的かつ重要な関数」の一つです。

  • ループ内で使用することで、記事の個別URLを自動出力する。
  • 出力（echo）まで行うため、記述がシンプルになる。
  • 値を加工したい場合は get_permalink() を選択する。
  • パーマリンク設定の変更に柔軟に対応できるため、メンテナンス性が高い。

Webサイトの構造を動的に保つことは、SEO対策やユーザーエクスペリエンスの向上に直結します。

手動でのリンク管理を極限まで減らし、WordPressの標準機能を最大限に活かしたスマートなサイト運営を心がけましょう。

今回紹介した基本操作と応用術をマスターすれば、より複雑なカスタムテーマ制作においても、リンク周りの実装で迷うことはなくなるはずです。

クラウドSSLサイトシールは安心の証です。

URLをコピーしました！