Extract sections from README.md in a typical ClassicPress plugin.

codepotent-readme-sections.php

<?php

	namespace CodePotent\Readme2Sections;

	// Usage
	$readme_file = 'https://gist.githubusercontent.com/johnalarcon/c19d3111dc73578a3fe224084e2194ec/raw/9a9facfc849e915851fd99cbb6495ded9904340a/README.md';
	$readme_lines = file($readme_file);
	$sections_array = get_sections($readme_lines);

	// Result
	echo '<h3>Extract Sections from README.md</h3>';
	echo '<p><strong>Source</strong>: <a href="'.$readme_file.'">'.$readme_file.'</a></p>';
	echo '<p><strong>Result</strong>:</p>';
	echo '<pre>';
	print_r($sections_array);
	echo '</pre>';

	/**
	 * Get sections whitelist
	 *
	 * This function returns an array used for finding and whitelisting a select
	 * number of the sections that may be present in a plugin's README.md file.
	 *
	 */
	function get_section_whitelist() {
		return [
			'description'    => 'description',
			'faq'            => 'frequently asked questions',
			'installation'   => 'installation',
			'screenshots'    => 'screenshots',
			'reviews'        => 'reviews',
			'other_notes'    => 'other notes',
			'changelog'      => 'changelog',
			'upgrade_notice' => 'upgrade notice',
		];
	}

	/**
	 * Get data for whitelisted sections
	 *
	 *
	 *
	 * @param array $lines
	 * @return array[][]
	 */
	function get_sections(&$lines) {

		// Particular sections of interest.
		$natural_sections = get_section_whitelist();

		// Throw my thing down, flip it, and reverse it. ~ Missy Elliot
		$inverse_sections = array_flip($natural_sections);

		// Initialization.
		$sections = [];

		// Flag.
		$started = false;

		// Iterate over lines.
		foreach ($lines as $line) {
			// Check flag; skip everything until a section is reached.
			if (!$started && strpos($line, '==') !== 0) {
				continue;
			}
			// Capture headings.
			if (strpos($line, '==') === 0) {
				// Ok, we're started...raise the flag!
				$started = true;
				// Capture the heading.
				$heading = trim(str_replace('==', '', strtolower($line)));
				// Capture only the whitelisted headings.
				if (!empty($inverse_sections[$heading])) {
					$sections[$inverse_sections[$heading]] = []; // Nope, remove it.
				} else {
					$sections[$heading][] = $heading; // Yep, whitelisted.
				}
				// The line was a heading; no need to go further; continue.
				continue;
			}

			/**
			 * If here, the line is part of the last-found $heading array. It is
			 * stored in $sections[$heading][]
			 */
			if (!empty($inverse_sections[$heading])) {
				$sections[$inverse_sections[$heading]][] = $line;
			} else {
				$sections[$heading][] = $line;
			}

		}

		// Remove any unexpected sections.
		foreach (array_keys($sections) as $heading) {
			if (empty($natural_sections[$heading])) {
				unset($sections[$heading]);
			}
		}

		// Return the sections data.
		return $sections;

	}