Skip to content

[Enhancement] Multi-layer page border support for .pageformat#519

Description

@CarmJos

Before submitting

  • I am using the latest version of Quarkdown.
  • I have checked the wiki to confirm this feature doesn't already exist.
  • I have searched existing issues for duplicates.

Description

Currently, .pageformat's bordertop, borderright, borderbottom, and borderleft parameters accept a single Size value (e.g. 4px, 1cm), which only allows a simple solid border with uniform thickness. This is insufficient for users who want richer page border styles commonly found in word processors like Microsoft Word.

This proposal introduces multi-layer border support, enabling users to define compound borders composed of multiple concentric layers from outer to inner, each with its own width and style. It also adds a bordermargin parameter to control the offset of the border from the content area edge, and expands the set of available border styles with fine-grained control options.

Proposed syntax or behavior

1. Multi-layer border syntax

Each border side parameter (bordertop, borderright, borderbottom, borderleft) should accept a comma-separated list of border layers. Each layer follows the format:

<width> [style] [style-specific-options...]

Layers are rendered from outer to inner (first layer = outermost). Example:

.pageformat bordertop:{4px, 1px none, 2px dotted}

This creates, from outside to inside:

  1. 4px solid border
  2. 1px gap (no border)
  3. 2px dotted border

A single value (the current syntax) should remain valid as shorthand for a single-layer border:

.pageformat bordertop:{4px}

2. Border styles

The following styles should be supported. When omitted, the default is solid.

Style CSS equivalent Description
solid border-style: solid Solid line (default)
dotted border-style: dotted Dotted line
dashed border-style: dashed Dashed line
waved custom Wavy line (no CSS equivalent; requires custom rendering)

3. Style-specific options

Each style supports optional parameters for fine-grained control. These are specified as key-value pairs after the style name.

dotted -- controls dot size and spacing:

2px dotted [dotsize] [spacing]

dashed -- controls dash length and spacing:

2px dashed [length] [spacing]

waved -- controls wave amplitude and period:

2px waved [amplitude] [period]

4. New bordermargin parameter

A new bordermargin parameter should be added, accepting 4 Size values (top, right, bottom, left), to control the distance between the border and the page content edge:

.pageformat bordermargin:{10px 15px 10px 15px}

This maps to padding/margin between the content area boundary and the border rendering position.

5. Backward compatibility

  • A single Size value (e.g. 4px) should continue to work as a single solid layer.
  • bordercolor should apply as the default color for all layers that do not specify their own color.
  • If bordercolor is not set, the default foreground text color is used (existing behavior).

6. Example

.pageformat \
    bordertop:{4px solid, 1px none, 2px dotted 3px} \
    borderbottom:{3px waved 4px 8px} \
    borderleft:{2px dashed 10px 5px} \
    bordercolor:{Red} \
    bordermargin:{10px 15px 10px 15px} \

Additional context

  • The primary inspiration is Microsoft Word's Page Border feature (Design > Page Borders), which supports box, shadow, 3-D, and custom borders with styles including solid, dashed, dotted, double, wavy, and more, with options for color, width, and art patterns.
  • The waved style has no direct CSS border-style equivalent and will require custom rendering, likely via SVG border-image or a background pattern. This may be the most complex part of the implementation.
  • The dotted and dashed style-specific options (dotsize, length, spacing) can leverage CSS border-image with a repeating pattern or background-image with repeating-linear-gradient for precise control, since CSS border-style: dotted/dashed offers no native spacing control.
  • The existing Container.BorderStyle enum (NORMAL, DASHED, DOTTED, DOUBLE) in quarkdown-core is a separate system for container borders and does not map directly to this feature, but the naming conventions should be kept consistent.
Image

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions