=== NPC Manual Generator for Advanced Custom Fields ===
Contributors: npc01
Donate link: https://n-pc.jp/
Tags: acf, custom-fields, documentation, manual, pdf
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Reads Advanced Custom Fields (ACF) field structures and automatically generates client-ready update manuals in Markdown and PDF formats.

== Description ==

When you hand off a WordPress site to a client, they often ask "where do I edit what?". NPC Manual Generator for Advanced Custom Fields parses the field structures defined by Advanced Custom Fields (ACF) and produces an update manual that operations staff can actually read - in Markdown and PDF.

Designed for real-world handoff use, the plugin renders Repeater / Flexible Content / Group nesting, translates ACF location rules into readable text, and bundles a Japanese-capable font for PDF output, so the result is something you can ship as a deliverable.

= Main features =

* Read ACF local JSON (`acf-json/group_xxx.json`) and field groups stored in the database
* Indented rendering for nested fields (Repeater / Flexible Content / Group)
* Formatted output of field type, required flag, instructions, choices, and more
* Location rule humanization (post type, taxonomy, page templates; resolves page/post titles when reading from the database)
* Live preview in the admin screen
* Markdown download (single file and Zip bundle)
* PDF download (single file - A4 portrait, IPAex Gothic bundled, header / footer / page numbers)
* Bulk Zip download with format selection (MD / PDF / Both)
* Paired filename rename when bundling so that the MD and PDF for the same group share the same suffix

= Translation =

All UI strings are wrapped with `__()` / `_e()` and the text domain `npc-manual-generator-for-advanced-custom-fields`. A Japanese translation is bundled (`languages/npc-manual-generator-for-advanced-custom-fields-ja.po`). Additional languages can be contributed through translate.wordpress.org.

= Roadmap =

* Template feature (rebrand the manual with your studio's logo and colors)
* Inline display in the post editor sidebar
* Sample value capture (pull one real post and show "currently entered as ...")
* Diff manuals (highlight changes since the previous output)
* Automatic screenshot insertion (capture the admin screen with a headless browser and embed in the PDF)

= Links =

* Official site: https://n-pc.jp/
* Developer blog: https://n-pc.jp/blog/

= Author =

npc - Freelance WordPress developer working with ACF since 2016. This plugin grew from in-house tools used to ship real client projects.

== Installation ==

= Standard installation (recommended) =

1. From the WordPress admin, go to Plugins -> Add New -> Upload Plugin and upload the plugin Zip file.
2. Activate "NPC ACF Manual Generator" from the Plugins list.
3. Open "ACF Manual" in the left admin menu to start using it.

= Manual upload (FTP) =

1. Unzip the package and upload the entire `npc-acf-manual-generator/` folder (including `vendor/` and `fonts/`) to `wp-content/plugins/`.
2. Activate the plugin from Plugins.
3. Open "ACF Manual" in the left admin menu.

= For developers (when cloning from Git) =

The `vendor/` directory is excluded from version control. Install the dependencies with Composer:

`composer install --no-dev --optimize-autoloader`

= Requirements =

* PHP: 7.4 or higher
* PHP extensions: `mbstring` (required), `gd` (required for PDF output), `zip` (required for bulk Zip download)
* WordPress: 6.0 or higher
* ACF: 6.0 or higher recommended (used to read field groups from the database; sample JSON output works without ACF)

== Frequently Asked Questions ==

= Is ACF required? =

No. Markdown / PDF generation from sample JSON works without ACF. ACF 6.0 or higher is recommended for reading actual field groups from the database.

= Does it work with ACF Free? =

The basic field types work with ACF Free. Repeater / Flexible Content require ACF Pro.

= PDF generation says it cannot run =

One of the following is the cause. The exact reason is shown in the admin notice.

* `vendor/autoload.php` is missing - run `composer install --no-dev`
* `fonts/ipaexg.ttf` is missing - place IPAex Gothic (IPA Font License v1.0) under `fonts/`
* PHP extension `gd` or `mbstring` is disabled - enable it on the server
* `wp-content/uploads/` is not writable - required to create a temporary directory

= Can I customize the PDF design with my own brand? =

Yes. The header comment of `includes/class-pdf-generator.php` documents six `apply_filters()` extension points (template path, header HTML, footer HTML, mPDF config, default font, final HTML). Add filters from `functions.php` or your own plugin to swap logos, colors, and layout.

= Are there performance concerns on large sites? =

The Markdown path is designed to handle 100 field groups within a few seconds. PDF generation for very large manuals (100+ pages) may require raising `WP_MEMORY_LIMIT` and the PHP execution time limit.

= How extensive is the location rule humanization? =

* Post type / taxonomy / user role slugs - converted to readable labels
* Page / post conditions - the actual page title is resolved
* If the referenced post is deleted - falls back to `[deleted: ID:xxxx]`
* Title resolution runs only for database-sourced groups (JSON-sourced groups show the raw ID)

= Where is the sample JSON? =

`sample-data/group_sample.json` is bundled. After activating the plugin, you can try Markdown / PDF generation from this sample even without ACF installed.

= I want to contribute a translation =

Contributions through the WordPress.org translation platform (translate.wordpress.org) are welcome.

= I want to use the filter hooks for white-label customization =

See the six `apply_filters()` calls described in the header comment of `includes/class-pdf-generator.php`:

* `npc_acf_manual_pdf_template_path` - swap the template file path
* `npc_acf_manual_pdf_header_html` - swap the header HTML
* `npc_acf_manual_pdf_footer_html` - swap the footer HTML
* `npc_acf_manual_pdf_mpdf_config` - swap the mPDF constructor arguments
* `npc_acf_manual_pdf_default_font` - swap the default font
* `npc_acf_manual_pdf_html` - swap the final HTML (last resort)

Add `add_filter()` calls from `functions.php` or your own plugin to apply your branding.

= How do I test locally? =

`sample-data/group_sample.json` works as a stand-in even when ACF is not installed. A pre-generated `sample-data/group_sample.pdf` is also bundled for reference.

== Screenshots ==

1. The "ACF Manual" menu added to the WordPress admin
2. Field group list (database and JSON sources side by side)
3. Both database-sourced and JSON-sourced field groups detected
4. Markdown preview rendered in the admin
5. Bulk download with format radio (MD / PDF / Both) and multi-select
6. Sample PDF page (A4 portrait, header / footer, location rules)
7. Repeater / Flexible Content / Group nested rendering in the PDF (vertical guide lines)
8. Plugin name and version displayed in the Plugins list

== Changelog ==

= 1.0.0 =
* First public release on WordPress.org
* Plugin assets (banner and icon) added for the plugin directory page

= 0.3.0 =
* Phase 3: PDF output for production deliverables
* Bundled mPDF 8.3 via Composer (vendor/ included in the distribution)
* Bundled IPAex Gothic (with the IPA Font License v1.0 text)
* Single-file PDF download (A4 portrait, 20mm margins, header / footer, page numbers)
* Hierarchy rendered with H2 / H3 + left-border guide lines
* Bulk Zip download format radio (MD / PDF / Both)
* Paired filename rename so MD and PDF for the same group share suffixes
* Per-row download buttons reorganized as MD / PDF icon buttons
* Admin notice when mPDF or the bundled font is missing
* Six `apply_filters()` extension points in PDF_Generator for white-label customization

= 0.2.0 =
* Phase 2: production-ready release
* Direct read of field groups stored in the ACF database
* Markdown download (single file and Zip bundle)
* Location rule resolution (post type / page title / taxonomy / user role)
* In-request static cache to reduce database load during bulk processing
* Same-name groups deduplicated with sequential rename in Zip
* Fallback display when ZipArchive is not available

= 0.1.0 =
* Phase 1: PoC release
* ACF JSON read, Markdown generation, admin preview
* Repeater / Flexible Content / Group nesting
* All 16 field types covered

== Upgrade Notice ==

= 1.0.0 =
First public release on WordPress.org. Stable and production-ready.

= 0.3.0 =
Adds PDF output (mPDF + bundled IPAex Gothic) and bulk download format selection. Production-deliverable quality.

= 0.2.0 =
Adds reading of field groups stored in the database and Markdown download. Production-ready.

= 0.1.0 =
Initial release.

== Third-party Licenses ==

This plugin bundles the following third-party software.

* **mPDF** (`mpdf/mpdf` 8.x): GPL-2.0-only. See `vendor/mpdf/mpdf/LICENSE.txt`.
* **IPAex Gothic Font** (`fonts/ipaexg.ttf`): IPA Font License Agreement v1.0. See `fonts/IPA_Font_License_Agreement_v1.0.txt`. Official: https://moji.or.jp/ipafont/license/

The mPDF dependencies are also bundled (all under compatible licenses):

* `setasign/fpdi` - MIT
* `psr/log` - MIT
* `psr/http-message` - MIT
* `paragonie/random_compat` - MIT
* `myclabs/deep-copy` - MIT
* `mpdf/psr-log-aware-trait` - GPL-2.0-only
* `mpdf/psr-http-message-shim` - GPL-2.0-only
