TITLE

DESCRIPTION

React

root

Project news and updates


comment

If you have any ideas to make it better, or if you have any questions,
you're welcome to suggest changes or start a conversation on 
our L<GitHub page|https://github.com/podlite/podlite-specs/discussions>.


Looking forward to working on the next release with your valuable input.


nested

AUTHORS

VERSION

head

CHANGES

D<Podlite> is an easy-to-use markup language with a simple, consistent
underlying document object model. Podlite can be used for writing language
documentation, for documenting programs and modules, as well as for
other types of document composition.


The Podlite is a purely descriptive mark-up notation, with no presentational
components.


Podlite documents are specified using D<directives|directive>, which are
used to declare configuration information and to delimit blocks of
textual content.


Every directive starts either with an equals sign (C<=>) followed
immediately by an identifier.


An D<identifier|Podlite identifiers> composed of an alphabetical character followed by 
any combination of alphanumeric characters. Alphabetic and numeric 
definitions encompass relevant Unicode characters. The underscore 
is consistently treated as alphabetic. Additionally, an identifier 
can include isolated apostrophes or hyphens, given that the subsequent
character is alphabetic.


Directives that start with C<=> can be indented like the code they
interleave, but their initial C<=> must still be the first non-whitespace
character on their line.


An indented Podlite block is considered to have a I<virtual left margin>,
determined by the indentation of its opening delimiter.


In other words, if a directive is indented from the left margin, the
column at which the first character of its opening delimiter appears is
thereafter considered the first column of the entire block's contents.


The virtual margin treats leading tabs as aligning to tabstops spaced 
every C<($?TABSTOP // 8)> characters.


The content of a document is specified within one or more D<blocks|block>.
Every Podlite block may be declared in any of three forms:
I<L<delimited style|#Delimited blocks>>, I<L<paragraph style|#Paragraph
blocks>>, or I<L<abbreviated style|#Abbreviated blocks>>.
All of these forms are equivalent.


Anything in a document that is neither a Podlite directive nor contained
within a Podlite block is treated as "ambient" material. Typically this
would be the source code of the program that the Podlite is documenting. 
Podlite parsers still parse this text into the internal representation of the
file, representing it as a "ambient" block. Renderers
will I<usually> ignore such blocks.
This is the D<default mode|Default mode; parser modes> of the parser.


All directives have a defined terminator and the Podlite parser always reverts to
D<"ambient"|Ambient mode; parser modes> at the end of each Podlite directive or 
block.


The C<=pod> block puts the parser in D<"pod" mode|Pod mode; parser modes>, 
treating all text between blocks as implicit paragraph Podlite, even if 
it's not inside an explicit block.


To keep the parser in "pod" mode, enclose the desired Podlite region 
in a C<=pod> block:


code

=begin code :allow<B>
  B<=begin pod>

  =head1 A heading

  This is Podlite too. Specifically, this is a simple C<para> block

      $this = pod('also');  # Specifically, a code block

  B<=end pod>
=end code


The contents of files with the extensions C<.podlite> and C<.pod6> are 
implicitly wrapped in a C<=pod> directive.


For C<.md> and C<.markdown> files, the parser operates in D<"Markdown" 
mode|Markdown mode; parser modes> for the entire file, treating all 
text as markdown even if it is not inside an C<=markdown> block.


Any other file extension puts the parser in default mode. The L<C<=include>
block|#Include block > has a mechanism to override this behavior by using 
the C<:mime-type> attribute for the included files.


Delimited blocks are bounded by C<=begin> and C<=end> markers, both of
which are followed by a valid Podlite identifier, which is the
D<typename> of the block. Typenames that are entirely lowercase (for
example: C<=begin head1>) or entirely uppercase (for example: C<=begin
SYNOPSIS>) are reserved.


After the typename, the rest of the C<=begin> marker line is treated as
configuration information for the block. This information is used in
different ways by different types of blocks, but is always specified using
any of:


table_head

 ===============   ===================   ==============   ======================


table_row

table

All option keys and values must, of course, be constants since Podlite is a
specification language, not a programming language. Specifically, option
values cannot be closures.


The configuration section may be extended over subsequent lines by
starting those lines with an C<=> in the first (virtual) column followed
by a whitespace character.


The lines following the opening delimiter and configuration are the
data or contents of the block, which continue until the block's matching
C<=end> marker line. For most block types, these contents may be
indented if you wish, without them being treated as L<code blocks|#Code
blocks>. Indented text is only treated as code within
C<=pod>, L<C<=nested>|#Nesting blocks>, L<C<=item>|#Lists>, C<=code>,
and L<semantic|#Semantic blocks> blocks.


=begin code :allow< R >
     =begin R<BLOCK_TYPE>  R<OPTIONAL CONFIG INFO>
     =                  R<OPTIONAL EXTRA CONFIG INFO>
     R<BLOCK CONTENTS>
     =end R<BLOCK_TYPE>
=end code


=begin code
     =begin table  :caption<Table of Contents>
         Constants           1

         Variables           10

         Subroutines         33

         Everything else     57
     =end table

        =begin Name  :required
        =            :width(50)
        The applicant's full name
        =end Name

        =begin Contact  :optional
            The applicant's contact details
        =end Contact
=end code


Note that no blank lines are required around the directives; blank
lines within the contents are always treated as part of the contents.
This is a universal feature of Podlite.


Note also that in the following specifications, a "blank line" is a line
that is either empty or that contains only whitespace characters. That
is, a blank line matches the following pattern: C</^^ \h* $$/>. Podlite uses
blank lines as delimiters, rather than empty lines, to minimize unpleasant
surprises when stray spaces or tabs mysteriously turn up in hitherto
empty lines.


Paragraph blocks are introduced by a C<=for> marker and terminated by
the next Podlite directive or the first blank line (which is I<not>
considered to be part of the block's contents). The C<=for> marker is
followed by the name of the block and optional configuration
information. The general syntax is:


=begin code :allow< R >
     =for R<BLOCK_TYPE>  R<OPTIONAL CONFIG INFO>
     =                R<OPTIONAL EXTRA CONFIG INFO>
     R<BLOCK DATA>
=end code


=begin code
     =for table  :caption<Table of Contents>
         Constants           1
         Variables           10
         Subroutines         33
         Everything else     57

        =for Name  :required
        =          :width(50)
        The applicant's full name

     =for Contact  :optional
        The applicant's contact details

=end code


Abbreviated blocks are introduced by an C<'='> sign in the
first column, which is followed immediately by the typename of the
block. The rest of the line is treated as block data, rather than as
configuration. The content terminates at the next Podlite directive or the
first blank line (which is not part of the block data). The general
syntax is:


Podlite - a lightweight markup language


Dive into the latest advancements in knowledge management with Podlite, a cutting-edge tool that's revolutionizing how we create and navigate information ecosystems. This article unveils the exciting new features of Podlite-web, from its revamped architecture and plugin support to smart navigation tools and seamless Markdown integration. We'll also introduce you to L<"The Raku Knowledge Base"|https://raku-knowledge-base.podlite.org>, a comprehensive resource that showcases these innovations in action. Whether you're a developer, technical writer, or knowledge management enthusiast, discover how Podlite is paving the way for more efficient, accessible, and dynamic information systems.


📖 Podlite: Enhancements for knowledge 
management and information ecosystems


Podlite keeps evolving, opening up new possibilities for knowledge management. Check out this list of recent achievements in the L<Podlite-web|https://github.com/podlite/podlite-web> package for creating web projects:


item

All these new features significantly expand Podlite-web's capabilities for creating modern, user-friendly, and informative web resources, especially in the areas of knowledge management and technical documentation.


Introducing the "The Raku Knowledge Base" project


We're excited to introduce a new project that showcases all the above-mentioned Podlite-web features in action - L<"The Raku Knowledge Base"|https://raku-knowledge-base.podlite.org>.


picture

This site is a comprehensive knowledge base for the Raku programming language, including:


It's worth noting that since Podlite supports Markdown out of the box, this knowledge base also incorporates a wide range of Markdown files. This feature significantly enhances the completeness and versatility of  L<"The Raku Knowledge Base"|https://raku-knowledge-base.podlite.org> resource, making it an even more comprehensive source of information about Raku.


caption

B<Open Source>: The source code for the L<"The Raku Knowledge Base"| https://raku-knowledge-base.podlite.org> project is available on GitHub: L<https://github.com/zag/raku-knowledge-base>. The community is invited to support the project by giving it a star 🌟!


B<Opportunity to Contribute>: The project is open for pull requests to add and improve information. Contributions from every member of the Raku community are welcome.


This resource is expected to become a valuable source of knowledge about the Raku language for both beginners and experienced developers.


Stay tuned for Podlite project updates - there's still a lot of exciting stuff coming!


If you have any tasks related to building information systems or knowledge bases, feel free to reach out at info@podlite.org. Proposals for development and support of projects on a commercial basis using Podlite are being considered.


Thanks for your attention and interest in the Podlite!


"Raku" is trademark of the Yet Another Society.


Project news and updates

2024OCTOBER

MAY

APRIL

FEBRUARY