git-md-toc

#!/usr/bin/env perl

=head1 NAME

git-md-toc - generate the table of content from the Markdown file(s)

=head1 SYNOPSIS

  git-md-toc [OPTIONS] [FILE...]

=head1 DESCRIPTION

Read an input and generate the table of content (TOC) based on the
markup of the file which is assumed Markdown formatted. The outcome is
also formatted as Markdown.

The following HTML comments are recognized in a special way and handled
as the markers to insert new TOC or update existing one.

=over 4

=item C<< <!-- toc --> >>

is used to point the place in the document for putting a new TOC.

=item C<< <!-- toc-begin --> >>, C<< <!-- toc-end --> >>

are used to point the beginning and end of the existing TOC.

=back

Be noticed that these markers themselves must be sticky to the left edge
of the lines where they are situated. This rule doesn't spread on the
content within.

The updated TOC is always ended with double new line to separate from
the further text below. On the same reason, if the TOC is preceded with
some text above, the double new line is prepending the TOC.

=head2 Old-style markers

Early, before 2022, another set of markers was used: C<md-toc>,
C<md-toc-begin> and C<md-toc-end>.

Currently they are considered obsolete and not recommended in use. However
they are still supported but replaced with the newer ones when TOC
is updated.

Be noticed that you shouldn't mix old and new paired markers to designate
the beginning and end of the same TOC.

=head1 OPTIONS

=over 4

=item B<-h>, B<--help>

Print this help and exit.

=item B<-t> I<TITLE>, B<--title>=I<TITLE>

Specify the title for the TOC. If C<TITLE> is not specified or it's
empty value, the default value C<Table of Content> is assumed.

=item B<-l> I<LEVEL>, B<--level>=I<LEVEL>

Set the header level used for the TOC title. Available values are C<1>
to C<6>. The default value is C<1>.

=item B<-d> I<DEPTH>, B<--depth>=I<DEPTH>

Use C<DEPTH> to control how many levels of headers to include in the
TOC. Available values are C<1> to C<6>. Defaults to C<6>.

=item B<-T> I<TEXT_ENCODE,TITLE_ENCODE>, B<--transcode>=I<TEXT_ENCODE,TITLE_ENCODE>

Point encodings for the file content or the TOC title. It should
be specified explicitly to correctly parse inputs in UTF-8 or other
encodings.

The first value tells that both text and TOC title come in the particular
encoding.

The second value specifies encoding for the TOC title only. It can be
useful in DOS sessions for setting another encoding for the TOC title
declared in the command line. For example, to correctly set the TOC title
in Cyrillic in UTF8 encoded files I had to separately declare C<cp1251>
for the TOC title encoding.

=item B<--title-transcode>=I<TITLE_ENCODE>

Point another encoding for the TOC title. It works similarly as
C<--transcode=,TITLE_ENCODE> (note the comma in the option).

This option is obsolete and kept for compatibility reasons. Use
B<-T>/B<--transcode> instead.

=item B<-u>, B<--update>

Update the file with the new table of content. It works even when reading
from STDIN. In this case the outcome will be printed to STDOUT.

=item B<-c>, B<--create-before>

=item B<-C>, B<--create-after>

Create and add the TOCs before and/or after the input.

In combination with the B<-u>/B<--update> option they allow to create and
insert the TOCs from the scratch even if no any TOC marker is specified.

=item B<--folding>=I<collapse|expand>

Make TOC foldable. Two values C<collapse> and C<expand> are enabled.

If specified, the B<-t>/B<--title> option is implied.

When the document has many sections and TOC becomes correspondingly
quite big, it can be more friendly to make TOC foldable.

=back

=head1 SEE ALSO

=head2 Syntax specification

=over 4

=item L<https://daringfireball.net/projects/markdown/>

=back

=head2 Perl implementations

=over 4

=item L<https://metacpan.org/pod/Text::Markdown>

=item L<https://metacpan.org/pod/Text::MultiMarkdown>

=item L<https://metacpan.org/pod/Markdown::TOC>

=back

=head2 Some other implementations

=over 4

=item L<https://github.com/ekalinin/github-markdown-toc>

=item L<https://github.com/ekalinin/github-markdown-toc.go>

=item L<https://github.com/frnmst/md-toc>

=item L<https://github.com/eGavr/toc-md>

=item L<https://github.com/jonschlinkert/markdown-toc>

=back

=head1 AUTHORS

Ildar Shaimordanov E<lt>F<ildar.shaimordanov@gmail.com>E<gt>

=head1 COPYRIGHT

Copyright (c) 2019-2022 Ildar Shaimordanov. All rights reserved.

  MIT License

=cut

use strict;
use warnings;

use Getopt::Long qw( :config no_ignore_case bundling );
use Pod::Usage;

my $toc_default_title = "Table of Content";
my $toc_title;
my $toc_level = 1;
my $toc_depth = 6;
my $update;
my $create_before;
my $create_after;
my $encode_text;
my $encode_title;
my $folding;
my $tag_fold = "<details%s><summary>\n\n%s\n\n</summary>\n\n%s\n\n</details>";
my $tag_fold_types = {
	collapse	=> "",
	expand		=> " open",
};

sub detect_int_range {
	my $int = shift;

	$int =~ /^[1-6]$/
	or die "Out of range [1..6]: $int\n";

	return $int;
}

sub detect_encoding {
	my $enc = shift;
	return unless $enc;

	use Encode;
	Encode::find_encoding($enc)
	or die "Encoding not found: $enc\n";

	return $enc;
}

exit 1 unless GetOptions(
	"h|help"	=> sub {
		pod2usage({ -verbose => 2, -noperldoc => 1 });
	},

	"t|title:s"	=> sub {
		$_[1] =~ s/^\s+//;
		$_[1] =~ s/\s+$//;
		$toc_title = $_[1] || $toc_default_title;
	},
	"l|level=i"	=> sub {
		$toc_level = detect_int_range($_[1]);
	},
	"d|depth=i"	=> sub {
		$toc_depth = detect_int_range($_[1]);
	},
	"T|transcode=s"	=> sub {
		$_[1] =~ s/^\s+//;
		$_[1] =~ s/\s+$//;
		my @e = split ",", $_[1];

		@e == 1 || @e == 2
		or die "$_[0]: One or two comma-separated values expected\n";

		$encode_text  = detect_encoding(shift @e);
		$encode_title = detect_encoding(shift @e);
	},
	"title-transcode=s"	=> sub {
		$encode_title = detect_encoding($_[1]);
	},
	"u|update"	=> \$update,
	"c|create-before"	=> \$create_before,
	"C|create-after"	=> \$create_after,
	"folding=s"	=> sub {
		$toc_title ||= $toc_default_title;
		$folding = $tag_fold_types->{ $_[1] };
		die "$_[0]: Only 'collapse' or 'expand' expected\n"
			unless defined $folding;
	},
);

pod2usage({ -verbose => 2, -noperldoc => 1 }) if -t 0 && @ARGV == 0;
@ARGV = "-" unless @ARGV;

# =========================================================================

my $name_toc		= "toc";
my $name_toc_begin	= "toc-begin";
my $name_toc_end	= "toc-end";

my $tag_toc		= "<!-- $name_toc -->";
my $tag_toc_begin	= "<!-- $name_toc_begin -->";
my $tag_toc_end		= "<!-- $name_toc_end -->";

my $re_toc = qr{
	^
	(?:
		<!-- [ \t]+ (?: md- )?	$name_toc	[ \t]+ --> [ \t\r]*
		|
		<!-- [ \t]+ ( md- | )?	$name_toc_begin	[ \t]+ --> [ \t\r]* \n
		(?: [\s\S]*? \n )*?
		<!-- [ \t]+ \1		$name_toc_end	[ \t]+ --> [ \t\r]*
	)
	$
}msx;

$encode_title ||= $encode_text;
$toc_title = decode($encode_title, $toc_title) if $encode_title && $toc_title;

foreach ( @ARGV ) {
	my $orig_text;
	{
		local $/;
		open F, $_ or die "Unable to open for reading: $_: $!\n";
		binmode F, ":encoding($encode_text)" if $encode_text;
		$orig_text = <F>;
		close F;
	};

	my $clean_text = $orig_text;

	# skip code fencing
	$clean_text =~ s{
		(?:\A|\n) [ \t]* (```|~~~) .*? \n [ \t]* \1
	}{}msgx;

	# skip any TOC markers
	$clean_text =~ s/$re_toc//g;

	# skip other HTML comments because they could contain markdown within
	$clean_text =~ s{
		(?:\A|\n) [ \t]* <!-- \s+ .*? \s+ -->
	}{}msgx;

	my %count = ();

	my @toc = ();

	while ( $clean_text =~ m{
		(?:\A|\n)
		[ ]{0,3}
		(?:
			# atx-style headers H1-H6
			( [#]{1,6} ) [ \t]+ ( .+? ) (?: [ \t]+ [#]* )?
			|
			# setext-style headers H1
			( \S[^\r\n]*? ) [ \t\r]* \n [ \t]* ( [=] )+
			|
			# setext-style header H2
			( (?![-]+)|[^\r\n]+? ) [ \t\r]* \n [ \t]* ( [-] )+
		)
		[ \t\r]*
		(?=\n)
	}mgx ) {
		my $depth;
		my $indent;
		my $title;

		if ( $1 && $2 ) {
			$depth = length($1);
			$title = $2;
		} elsif ( $4 && $3 ) {
			$depth = 1;
			$title = $3;
		} elsif ( $6 && $5 ) {
			$depth = 2;
			$title = $5;
		}

		next unless $title;
		next if $depth > $toc_depth;

		# Remove markdown images
		$title =~ s/\!\[.*?\]\(.*?\)//g;

		# Remove markdown links
		$title =~ s/\[(.*?)\]\(.*?\)/$1/g;

		# Remove html tags
		$title =~ s/<[^<>]*>//g;

		$indent = "  " x ( $depth - 1 );

		my $anchor = lc $title;
		$anchor =~ s/\s/-/g;
		$anchor =~ s/[^\w-]//g;

		$count{$anchor}++;

		$anchor .= ( 1 - $count{$anchor} or "" );

		# Avoid empty text within links
		$title =~ s/^\s*$/#/;

		push @toc, "$indent* [$title](#$anchor)";
	}

	my $toc = join "\n", @toc;

	$toc_title = "#" x $toc_level . " $toc_title"
		if $toc_title;

	$toc = sprintf $tag_fold, $folding, $toc_title, $toc
		if defined $folding;

	$toc = "$toc_title\n$toc"
		if $toc_title && ! defined $folding;

	$toc = "$tag_toc_begin\n$toc\n$tag_toc_end";

	unless ( $update ) {
		binmode STDOUT, ":encoding($encode_text)" if $encode_text;
		print "$toc\n";
		next;
	}

	$orig_text =~ s/$re_toc/$toc/g;

	# create TOCs before or after the input if requested
	$orig_text = "$toc\n\n$orig_text" if $create_before;
	$orig_text = "$orig_text\n$toc\n" if $create_after;

	warn "Updating $_\n";

	open F, ">$_" or die "Unable to open for writing: $_: $!\n";
	binmode F, ":encoding($encode_text)" if $encode_text;
	print F $orig_text;
	close F;
}

# =========================================================================

# EOF