docs: prepare user-focused MarkdownViewr product page
Add real reader screenshots, user and developer guides, current contribution/support links, and verified OpenSSF enrollment evidence. Refs #31, #33, #34. Co-Authored-By: Codex GPT-6 <noreply@openai.com> Signed-off-by: James Maes <james@kof22.com>
This commit is contained in:
13 files changed
+310
-359
No files matched your search
@@ -11,7 +11,7 @@ body:
|
||||
id: version
|
||||
attributes:
|
||||
label: Version
|
||||
description: The exact version (Help, About, or `--version`).
|
||||
description: The exact version shown in Help → About, including stable or dev edition.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: User guide
|
||||
url: https://github.com/KofTwentyTwo/MarkdownViewr.Windows/blob/main/docs/user-guide.md
|
||||
about: Opening files, themes, printing, default apps, and troubleshooting.
|
||||
- name: Community support
|
||||
url: https://github.com/KofTwentyTwo/MarkdownViewr.Windows/discussions
|
||||
about: Ask usage questions or discuss ideas with the community.
|
||||
- name: Report a security vulnerability
|
||||
url: https://github.com/KofTwentyTwo/MarkdownViewr.Windows/security/advisories/new
|
||||
about: Please report security issues privately, never as a public issue.
|
||||
+25
-131
@@ -1,151 +1,45 @@
|
||||
# Contributing to MarkdownViewr
|
||||
|
||||
Thanks for helping. This project follows the
|
||||
[KofTwentyTwo standards](https://github.com/KofTwentyTwo/standards); this page is the
|
||||
short version of what they ask of a contribution.
|
||||
Questions, bug reports, documentation improvements, and code contributions are welcome. For everyday use, start with the [user guide](docs/user-guide.md). For build commands and tests, use [DEVELOPERS.md](DEVELOPERS.md).
|
||||
|
||||
## Before you start
|
||||
|
||||
For anything beyond a small fix, open an issue first so the approach can be agreed
|
||||
before you invest time. Questions and proposals are welcome in
|
||||
[Issues](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/issues).
|
||||
For a substantial change, open an [issue](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/issues/new/choose) first to agree on the approach. Ask usage questions in [Discussions](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/discussions).
|
||||
|
||||
## Setup
|
||||
Report security vulnerabilities privately according to [SECURITY.md](SECURITY.md). Do not include private documents, credentials, or personal information in reports, screenshots, or test fixtures.
|
||||
|
||||
Prerequisites: Windows 10 1809 or later, the .NET 10 SDK (`global.json` pins the feature
|
||||
band), and optionally Visual Studio 2026 or Rider. The
|
||||
[workstation setup](https://github.com/KofTwentyTwo/standards#set-up-your-machine)
|
||||
installs everything, including the git hooks' tools. The commands below are exactly what
|
||||
CI runs; run them before pushing.
|
||||
## Development workflow
|
||||
|
||||
```powershell
|
||||
dotnet restore MarkdownViewr.Windows.slnx -p:Platform=x64 --locked-mode
|
||||
dotnet build MarkdownViewr.Windows.slnx -p:Platform=x64 -warnaserror
|
||||
This Product follows the [KofTwentyTwo standards](https://github.com/KofTwentyTwo/standards).
|
||||
|
||||
# Unit tests, then the 100% line-coverage gate over every measured assembly
|
||||
dotnet test MarkdownViewr.Windows.slnx -p:Platform=x64 --no-build --filter "FullyQualifiedName!~UiTests" --settings coverage.runsettings --collect:"XPlat Code Coverage" --results-directory TestResults
|
||||
./build/Assert-Coverage.ps1 -ResultsDirectory TestResults
|
||||
1. Branch from `main` using `<type>/<short-description>`, for example `fix/source-highlighting`.
|
||||
2. Follow the [developer guide](DEVELOPERS.md), install both pre-commit and commit-msg hooks, and run the relevant quality gates.
|
||||
3. Make signed, signed-off [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): `git commit -S -s`.
|
||||
4. Open a pull request targeting `main` with a Conventional Commit title. PRs are squash merged.
|
||||
5. Resolve all review threads and required checks before merging.
|
||||
|
||||
# End-to-end UI tests: FlaUI launches the app (needs an interactive desktop)
|
||||
dotnet test tests/MarkdownViewr.Windows.UiTests
|
||||
## Pull request checklist
|
||||
|
||||
# Style gate (Kingsrook layout, analyzers, naming)
|
||||
dotnet format MarkdownViewr.Windows.slnx --verify-no-changes --severity warn --no-restore
|
||||
- Explain the problem, resulting behavior, and linked issues.
|
||||
- Report the checks you actually ran and any limitations.
|
||||
- Include screenshots for UI changes and update user documentation.
|
||||
- Retain zero-warning builds, clean formatting, and 100% measured core line coverage.
|
||||
- Add regression tests for fixes; exercise native and installed behavior where relevant.
|
||||
- Justify dependency changes and commit regenerated locks.
|
||||
- Update the [threat model](docs/security/threat-model.md) for attack-surface changes.
|
||||
- Preserve original MIT notices and dependency credits.
|
||||
- Disclose substantial AI assistance and include a `Co-Authored-By:` trailer naming the model.
|
||||
|
||||
# PowerShell tooling gate (install PSScriptAnalyzer 1.25.0 once)
|
||||
Import-Module PSScriptAnalyzer -RequiredVersion 1.25.0
|
||||
# Load repository command metadata; keep casing separate from other analyzer rules.
|
||||
Import-Module ./build/GitHubRepository.psm1 -Force
|
||||
foreach($script in Get-ChildItem build -File | Where-Object Extension -In '.ps1', '.psm1', '.psd1') {
|
||||
$findings = @(
|
||||
Invoke-ScriptAnalyzer -Path $script.FullName -Settings ./PSScriptAnalyzerSettings.psd1 -IncludeRule PSUseCorrectCasing
|
||||
Invoke-ScriptAnalyzer -Path $script.FullName -Settings ./PSScriptAnalyzerSettings.psd1 -ExcludeRule PSUseCorrectCasing
|
||||
)
|
||||
if($findings.Count -ne 0) { $findings | Format-Table; throw 'Script analysis failed.' }
|
||||
}
|
||||
Import-Module Pester -RequiredVersion 5.7.1
|
||||
Invoke-Pester -Path build/*.Tests.ps1 -CI
|
||||
```
|
||||
Required CI covers build/coverage/style, reader and installed-update acceptance, parser fuzzing, tooling tests, dependency/secret/workflow scans, CodeQL, PR title, and DCO.
|
||||
|
||||
`dotnet format` (without `--verify-no-changes`) fixes layout, `var` use, usings, and
|
||||
line endings. Two Kingsrook rules it cannot apply are checked in review: three blank
|
||||
lines between members, and a header comment on every type and method (Rider and
|
||||
ReSharper apply the blank lines from `.editorconfig`). Changing a package version means
|
||||
updating `Directory.Packages.props` and committing the regenerated `packages.lock.json`
|
||||
files (`dotnet restore MarkdownViewr.Windows.slnx -p:Platform=x64 --force-evaluate`).
|
||||
Under the single-maintainer policy, `review / automated` also requires a genuine current-commit acknowledgement from the configured human maintainer. An agent cannot provide that acknowledgement. See [repository setup](docs/repository-setup.md).
|
||||
|
||||
Install the git hooks once per clone (the hook configuration comes from
|
||||
[KofTwentyTwo/standards](https://github.com/KofTwentyTwo/standards/tree/main/configs/pre-commit)):
|
||||
## Sign-off and license
|
||||
|
||||
```sh
|
||||
pre-commit install --hook-type pre-commit --hook-type commit-msg
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Branch from `main` with a short-lived topic branch named `<type>/<short-description>`,
|
||||
for example `feat/export` or `fix/42-splash-never-dismisses`.
|
||||
2. Commit with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
|
||||
(`feat: ...`, `fix(settings): ...`). Every commit is **signed** and **signed off**:
|
||||
`git commit -S -s` (see *Sign-off* below).
|
||||
3. Open a pull request against `main`. Its title must itself be a Conventional Commit
|
||||
header: pull requests are **squash-merged**, so the title becomes the commit message on
|
||||
`main`.
|
||||
4. Every required check must pass, and every review thread must be resolved, before the
|
||||
pull request merges.
|
||||
|
||||
## What makes a contribution acceptable
|
||||
|
||||
- The build has **zero warnings**, and the format gate is clean.
|
||||
- New behavior has tests; a bug fix has a test that fails without the fix.
|
||||
- Line coverage of `MarkdownViewr.Windows.Core` stays at **100%**. Logic goes in `MarkdownViewr.Windows.Core`; the
|
||||
WinUI project holds views and framework plumbing only
|
||||
([ADR-0001](docs/adr/0001-adopt-the-windows-desktop-reference-architecture.md)).
|
||||
- User-visible changes update the docs in the same pull request; attack-surface changes
|
||||
update the [threat model](docs/security/threat-model.md).
|
||||
- No secrets, credentials, or personal data, ever.
|
||||
- New dependencies are justified in the pull request description.
|
||||
|
||||
## Checks that gate a merge
|
||||
|
||||
| Check | What it verifies |
|
||||
| --- | --- |
|
||||
| `pr / title` | The PR title is a Conventional Commit header |
|
||||
| `pr / dco` | Every commit is signed off |
|
||||
| `pr / dependency-review` | Added dependencies have no known vulnerabilities and an allowed license |
|
||||
| `fuzzing` | Repeatable parser security properties; longer weekly and release campaigns |
|
||||
| `security / secrets`, `security / sca`, `security / workflows` | No secrets, no vulnerable or malicious dependencies, safe workflows |
|
||||
| `codeql / analyze (csharp)`, `codeql / analyze (actions)` | No high-severity static analysis findings |
|
||||
| `ci / build-test` | Locked restore, zero-warning build, unit tests, 100% coverage gate |
|
||||
| `ci / format` | `dotnet format --verify-no-changes --severity warn` |
|
||||
| `ci / ui-tests` | FlaUI end-to-end tests of the app |
|
||||
| `installed-updates` | Real stable/dev installers, upgrades, restart and published-output UI smoke |
|
||||
| `powershell`, `javascript` | Tool lint, setup/coverage boundary tests, review tests and dependency signatures |
|
||||
| `codeql / analyze (javascript-typescript)` | Static analysis of repository review tooling |
|
||||
| `review / automated` (single maintainer) | Current-commit automated review acknowledged by the configured human maintainer |
|
||||
|
||||
Run `npm ci --ignore-scripts`, `npm run lint` and `npm test` for repository JavaScript.
|
||||
CI checks `PSUseCorrectCasing` alone, then all remaining rules, using the unchanged
|
||||
settings and failing on every finding or engine exception. This avoids the observed
|
||||
1.25.0 command-metadata race; neither pass disables a required rule. Negative fixtures
|
||||
verify both partitions still report violations. For the same local workaround, supply
|
||||
`-IncludeRule PSUseCorrectCasing` and then `-ExcludeRule PSUseCorrectCasing` in two
|
||||
sequential `Invoke-ScriptAnalyzer` calls; evaluate findings from both.
|
||||
Run PSScriptAnalyzer with `PSScriptAnalyzerSettings.psd1` and Pester against
|
||||
`build/*.Tests.ps1`. New owners follow [repository setup](docs/repository-setup.md).
|
||||
|
||||
## Parser campaigns
|
||||
|
||||
Run the [seeded parser targets](docs/security/fuzzing.md) when changing document,
|
||||
source, URL, theme-import or activation boundaries. The required `fuzzing` check
|
||||
runs PR/main budgets; weekly and release gates use longer campaigns. Retain and
|
||||
minimize failing synthetic inputs into regression cases. Never execute generated
|
||||
content or use private files/profiles as a corpus. Best Practices enrollment and
|
||||
actual signing remain separate maintainer requirements.
|
||||
|
||||
## Sign-off (Developer Certificate of Origin)
|
||||
|
||||
By signing off a commit you certify the
|
||||
[Developer Certificate of Origin 1.1](https://developercertificate.org/): that you wrote
|
||||
the change, or otherwise have the right to submit it under the project's license.
|
||||
`git commit -s` appends the sign-off:
|
||||
Signing off certifies the [Developer Certificate of Origin 1.1](https://developercertificate.org/): you wrote the contribution or have the right to submit it under the project's license. `git commit -s` adds:
|
||||
|
||||
```text
|
||||
Signed-off-by: Your Name <your.email@example.com>
|
||||
```
|
||||
|
||||
The name and email must match the commit author. To add missing sign-offs to a branch,
|
||||
run `git rebase --signoff main` and force-push the branch.
|
||||
|
||||
## AI-assisted contributions
|
||||
|
||||
AI coding tools are welcome. You remain the author: you must understand, test, and be
|
||||
able to explain every line you submit, and you sign it off as your own. Note substantial
|
||||
AI assistance in the pull request description.
|
||||
Include a Co-Authored-By trailer naming the model for significant AI contributions
|
||||
(K22-AGENT-40 / K22-AI-02).
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions are licensed under the project's
|
||||
[MIT License](LICENSE).
|
||||
The sign-off must match the commit author. Contributions are licensed under the project's [MIT License](LICENSE). AI assistance does not remove your responsibility to understand, test, and explain the change.
|
||||
@@ -0,0 +1,92 @@
|
||||
# Developer Guide
|
||||
|
||||
For installation and everyday use, see the [README](README.md) and [user guide](docs/user-guide.md). Contribution requirements are in [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## Environment and structure
|
||||
|
||||
Use Windows 10 1809 or later, Microsoft Edge WebView2 Runtime, and the .NET 10 SDK selected by `global.json`. The current release target is Windows x64.
|
||||
|
||||
- `src/MarkdownViewr.Windows.Core/`: testable document, rendering, theme, and view-model logic.
|
||||
- `src/MarkdownViewr.Windows/`: WinUI views, WebView2 integration, Windows adapters, and `Assets/Brand/`.
|
||||
- `tests/`: xUnit core tests, native/published UI acceptance, and installed-update probes.
|
||||
- `build/`: coverage, repository setup, packaging, signing, and lifecycle validation.
|
||||
- `docs/`: product scope, ADRs, security evidence, and release runbooks.
|
||||
|
||||
Keep core logic independent of WinUI. Treat documents, renderer messages, resource URLs, and imported themes as untrusted; review the [threat model](docs/security/threat-model.md) before changing those boundaries.
|
||||
|
||||
## Restore, build, and run
|
||||
|
||||
Run from the repository root:
|
||||
|
||||
```powershell
|
||||
dotnet restore MarkdownViewr.Windows.slnx -p:Platform=x64 --locked-mode
|
||||
dotnet build MarkdownViewr.Windows.slnx -p:Platform=x64 -warnaserror
|
||||
dotnet run --project src/MarkdownViewr.Windows -p:Platform=x64
|
||||
```
|
||||
|
||||
To isolate preview data, set `MARKDOWNVIEWR_WINDOWS_DATA_DIR` for that process to a disposable absolute folder. Do not use another person's profile or interfere with an existing preview.
|
||||
|
||||
## Tests and quality gates
|
||||
|
||||
```powershell
|
||||
dotnet test tests/MarkdownViewr.Windows.Core.Tests --settings coverage.runsettings --collect:"XPlat Code Coverage" --results-directory TestResults
|
||||
./build/Assert-Coverage.ps1 -ResultsDirectory TestResults
|
||||
dotnet format MarkdownViewr.Windows.slnx --verify-no-changes --severity warn --no-restore
|
||||
npm ci --ignore-scripts
|
||||
npm run lint
|
||||
npm test
|
||||
```
|
||||
|
||||
Core tests use xUnit and Coverlet; retain 100% measured core line coverage. Name tests `Method_Scenario_Expectation` and add meaningful regression coverage for fixes. Deterministic tests inject time and filesystem boundaries.
|
||||
|
||||
Native desktop tests use FlaUI/UIA3 and require an available interactive desktop:
|
||||
|
||||
```powershell
|
||||
dotnet test tests/MarkdownViewr.Windows.UiTests
|
||||
```
|
||||
|
||||
Reserve the desktop before running physical-input tests. Hosted CI also exercises published output and actual stable/dev installation, update/restart, registration, and coexistence. See [installed-update acceptance](docs/installed-updates.md). Synthetic unsigned fixtures do not establish production signing.
|
||||
|
||||
For PowerShell, use PSScriptAnalyzer 1.25.0 with `PSScriptAnalyzerSettings.psd1`, then Pester 5.7.1 against `build/*.Tests.ps1`. Reproduce the exact sequential analyzer partitions and negative fixtures in [scripts.yml](.github/workflows/scripts.yml); engine exceptions and rule findings are failures.
|
||||
|
||||
Run the [seeded parser campaigns](docs/security/fuzzing.md) when changing parser or activation boundaries. Never use private documents as a corpus.
|
||||
|
||||
## Style and dependencies
|
||||
|
||||
Follow `.editorconfig`: three-space C# indentation, Allman braces, file-scoped namespaces, PascalCase public members, and `_camelCase` private fields. Keep type/method header comments and three blank lines between members. YAML uses two spaces.
|
||||
|
||||
Package versions live in `Directory.Packages.props`. After a deliberate version change, regenerate and commit affected locks:
|
||||
|
||||
```powershell
|
||||
dotnet restore MarkdownViewr.Windows.slnx -p:Platform=x64 --force-evaluate
|
||||
pre-commit install --hook-type pre-commit --hook-type commit-msg
|
||||
```
|
||||
|
||||
Use `dotnet format` without `--verify-no-changes` for supported formatting fixes; inspect the diff before committing.
|
||||
|
||||
## Releases and verification
|
||||
|
||||
Follow [RELEASING.md](docs/RELEASING.md), [signing](docs/release-signing.md), and [repository setup](docs/repository-setup.md). Stable tags use `v1.2.3`; prereleases such as `v1.2.3-beta.1` publish to the isolated development channel.
|
||||
|
||||
The protected release builder signs owned binaries before packaging, verifies distributed signatures, and generates final checksums and attestations. Never bypass signing failures or publish fixture packages.
|
||||
|
||||
After publication, download the actual assets and verify them:
|
||||
|
||||
```powershell
|
||||
Get-FileHash ./markdownviewr-windows-stable-Setup.exe -Algorithm SHA256
|
||||
gh attestation verify ./markdownviewr-windows-stable-Setup.exe --repo KofTwentyTwo/MarkdownViewr.Windows --signer-repo KofTwentyTwo/standards
|
||||
Get-AuthenticodeSignature ./markdownviewr-windows-stable-Setup.exe | Format-List Status, SignerCertificate
|
||||
signtool verify /pa /all /v ./markdownviewr-windows-stable-Setup.exe
|
||||
```
|
||||
|
||||
Compare hashes with the published `SHA256SUMS`; confirm publisher, trust, and RFC3161 timestamp. Verify both packages and their shipped payloads using the release runbook.
|
||||
|
||||
## Branding
|
||||
|
||||
The AppKit BrandTool generates the vector and multi-size ICO assets:
|
||||
|
||||
```powershell
|
||||
brandtool --out src/MarkdownViewr.Windows/Assets/Brand --start '#1A2B4D' --end '#0C1836' --glyph 'M 144 328 V 184 L 208 260 L 272 184 V 328 M 344 184 V 328 M 312 296 L 344 328 L 376 296 M 144 380 H 376' --stroke 28
|
||||
```
|
||||
|
||||
Preserve original-author and dependency attribution in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) and the About dialog.
|
||||
@@ -1,148 +1,71 @@
|
||||
# MarkdownViewr
|
||||
# MarkdownViewr for Windows
|
||||
|
||||
> In development: a Windows counterpart to [Darin Kelkhoff's macOS markdownViewr](https://github.com/darinkelkhoff/markdownViewr) ([his website](https://kelkhoff.com/)), built with AppKit. Native/published and installed stable/dev reader acceptance passes on `b542dcd`; the newer `82256f3` is undergoing hosted verification. Full owner design/default-app acceptance, current standards assessment and signed production releases remain incomplete.
|
||||
Read Markdown comfortably, keep up with changes, and turn your notes into something worth sharing.
|
||||
|
||||
A Windows Markdown viewer with live reload, themes and document navigation.
|
||||
MarkdownViewr is a dedicated Windows reader for project documentation, notes, and README files. Open a document, choose a look you like, and focus on the words.
|
||||
|
||||
**[Release downloads](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/releases) · [User guide](docs/user-guide.md) · [Ask a question](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/discussions)**
|
||||
|
||||
> The first Windows release is being prepared. There are no published Windows downloads yet; the Releases page will contain the stable installer and development previews when publication completes.
|
||||
|
||||
[](https://scorecard.dev/viewer/?uri=github.com/KofTwentyTwo/MarkdownViewr.Windows)
|
||||
[](LICENSE)
|
||||
[](https://www.bestpractices.dev/en/projects/15417)
|
||||
[](https://scorecard.dev/viewer/?uri=github.com/KofTwentyTwo/MarkdownViewr.Windows)
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| **Tier** | Product ([scope](https://github.com/KofTwentyTwo/standards/blob/main/policies/README.md#scope)) |
|
||||
| **Standards** | Adopting [KofTwentyTwo standards](https://github.com/KofTwentyTwo/standards); built from the KofTwentyTwo Windows app template |
|
||||
| **Latest release** | [Releases](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/releases/latest) |
|
||||
|
||||
|
||||
Settings → Advanced contains the startup splash toggle, splash duration (500–30000 milliseconds) and startup update checks. Changes save immediately and apply on the next launch. The native toolbar keeps Print visible, aligns controls in a compact row and groups reading commands.
|
||||
## Make Markdown easier to read
|
||||
|
||||
## Install
|
||||
- **Make it your own.** Choose from 20 document palettes, customize typography, and use a light, dark, or system app appearance.
|
||||
- **Follow changes as they happen.** Saved edits refresh automatically. The footer shows the loaded file's modification time and flags an unsuccessful reload.
|
||||
- **Navigate long documents.** Show Contents, jump between headings, collapse sections, and find text.
|
||||
- **See how it is written.** Open the highlighted, read-only source alongside the document. The split starts at 50/50 and resizes by dragging.
|
||||
- **Share a finished document.** Print from the toolbar or save a PDF with separate print styling and optional actions to open the result or its folder.
|
||||
- **Stay in your workflow.** Open several documents, launch your configured editor, or open the current document's folder in Explorer.
|
||||
|
||||
No Windows release has been published. The following describes the planned release artifacts.
|
||||
Contents and Source start hidden. Turn them on when needed, or change their new-window defaults in **File → Settings → General**.
|
||||
|
||||
Download `markdownviewr-windows-stable-Setup.exe` from the
|
||||
[latest release](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/releases/latest) and run it. It
|
||||
installs per user (no administrator rights needed) and updates itself in place from
|
||||
**Help → Check for updates**. `markdownviewr-windows-stable-Portable.zip` is a portable build that
|
||||
does not self-update.
|
||||
|
||||
|
||||
Prerelease tags (`v1.2.3-beta.1`) publish to the `dev` channel
|
||||
(`markdownviewr-windows-dev-Setup.exe`); an installation only ever updates within its own channel.
|
||||
## Download and install
|
||||
|
||||
## Usage
|
||||
The planned Windows packages support **Windows 10 version 1809 or later and Windows 11, x64**. Microsoft Edge WebView2 Runtime is required. No .NET SDK is needed to use a release.
|
||||
|
||||
- **File → Open / Ctrl+O:** choose a Markdown document. A literal file path can also be supplied when launching the executable.
|
||||
- **Settings → Advanced → Choose default file types:** an installed copy opens Windows Default Apps so you can choose MarkdownViewr for `.md`, `.markdown`, `.mdown` or `.mkd`. `.txt` is optional. Windows 11 23H2+ opens this installation's app page; older versions open general Default Apps. Portable previews show installation guidance. Registration/routing tests pass locally; actual installed selection and Explorer acceptance remain pending.
|
||||
- **Source highlighting:** the native read-only source view uses document-theme accents adjusted for shell light/dark contrast. Windows high contrast takes precedence. Copy preserves visible original text/newline spelling without rich-text clipboard data; find/fold/reload share the committed snapshot. New native acceptance is prepared, not yet run.
|
||||
- **Live reload:** saves automatically refresh the document, including replacement saves. Deletion keeps the last version visible until the file is restored. The relative reading position is preserved.
|
||||
- **File → Reload:** reread the current file manually. Local images stay within the document folder; remote images and authored scripts/styles are blocked.
|
||||
- **File → Print / Ctrl+P:** choose a separate print theme, images/backgrounds, standard or matching font zoom, content width, borders and page padding. **Print...** opens Windows print UI; **Save PDF...** asks for a PDF destination. Cancel leaves the reading view unchanged. The earlier five hosted print cases passed in native, published and both installed builds. The owner-reported missing system dialog and PDF behavior still need current-build reproduction; wider options, readable-file verification and opt-in PDF/folder actions are implemented locally. Final production signatures remain unverified.
|
||||
- **Document toolbar:** TOC and H1–H6 depth appear on the left; source, minus/percentage/plus zoom, theme and external editor follow in the Mac reference order. **Print** is a primary toolbar command; **Theme** uses the Color icon. Native overflow keeps commands accessible in narrow windows. Buttons share View/File handlers; depth is disabled when TOC is hidden, and editors launch directly or offer named choices. New toolbar/shared-editor acceptance is pending.
|
||||
- **Reading zoom:** use the minus/percentage/plus toolbar or **View → Zoom in / Zoom out / Actual size**. `Ctrl++` (also `Ctrl+=`), `Ctrl+-` and `Ctrl+0` change only the reading window's font scale, bounded to 30–500%. Reload and theme changes retain it; the percentage button resets to 100%. Glyph/key/reload acceptance passes in native, published and installed stable/dev builds on `2639e2d`; broader theme/find/collapse combinations remain pending.
|
||||
- **View → Markdown extensions:** independently enable highlight (`==text==`), superscript (`^text^`), subscript (`~text~`) and underline (`++text++`). All start enabled; code stays literal. Choices are saved and applied to reloads.
|
||||
- **File → Settings:** open the resizable Windows settings window with Appearance, Document themes, Editors and Advanced navigation. Content-width changes save immediately across readers; **Apply custom CSS** saves the advanced CSS draft. Closing discards unapplied CSS. Theme/editor dialogs use the settings window as their owner and keep their own Save/Cancel. Current desktop acceptance is pending.
|
||||
- **View → Document theme:** choose one of Darin's 20 built-in palettes. The saved document palette is independent of the Windows shell theme; changing it retains the reading position.
|
||||
- **File → Settings → Themes → Edit current theme:** edit all palette colors, body/heading/code fonts, body/code sizes, heading levels 1–6, line height and custom CSS. Keep its name to override a built-in, or enter a new name to create a custom theme. Invalid input keeps the editor open. **Restore built-in themes** restores and enables the original palettes, keeping edited built-ins as uniquely named custom copies.
|
||||
- **Settings → Themes → Manage themes:** reorder, enable/disable, delete, create, copy or edit choices in a copied draft, including disabled themes. **Use selected** chooses and enables a default. Save updates all open readers; Cancel discards changes across editor/picker dialogs. Built-in deletion is restorable. **Next/Previous document theme** and `Ctrl+Shift+Down/Up` cycle enabled choices in saved order when reading has focus. New management acceptance is pending.
|
||||
- **Settings → Themes → Import / Export:** import multiple JSON files, choosing **Overwrite**, **Keep both** or **Skip** for each conflict. Compatible newer schemas require **Import anyway** confirmation. Invalid/oversized files are rejected independently. Export any visible theme, including disabled choices, to the selected JSON destination; version and metadata are retained. The manager can also import/export its copied draft. New transfer acceptance is pending.
|
||||
- **View → Table of contents:** show the heading sidebar, choose levels 1–6, and drag its divider to resize. Select a heading to jump there; collapse a selected section or all sections, then expand when ready. Matching section state survives reloads and document theme changes.
|
||||
- **Settings → Editors / File → Open in editor:** save named installed `.exe` editors, add/remove or move them in the list, and choose whether each opens the document or its folder. Save commits and refreshes all open readers; Cancel discards changes. One editor has a direct named action; several offer a submenu in saved order. A missing editor or document reports a status message; the viewer remains open. Named list/folder/cancel/removal acceptance passes in native, published and both installed channels on `2639e2d`.
|
||||
- **Edit → Find / Ctrl+F:** search the rendered document and literal source, with one occurrence count and wrapping **Next/Previous** controls. Enter moves forward, Shift+Enter moves back, and Escape closes find. Search temporarily reveals collapsed sections; closing it restores prior choices and retains explicit section commands made during search.
|
||||
- **Reading keys:** `j/k` move a line; `Ctrl+D/U` move half a viewport; `gg/G` go to the beginning/end; `]]/[[` visit visible headings; `/` opens native find and `n/N` advance/reverse its matches. Escape closes find. Prefixes expire after 500 ms; typing in find/theme/editor controls retains normal behavior. Windows `Ctrl+F` opens find; `Ctrl+B` moves back a viewport. Physical-key acceptance has passed in hosted native, published and installed builds.
|
||||
- **View → Markdown source:** show the literal, read-only snapshot beside the reader, including frontmatter and fenced code. Visibility persists; every window and reopening starts at 50/50. Drag the divider left/right, or focus it and use Left/Right arrows; Home restores equal panes. The outline is excluded from the split, and saves refresh both surfaces. New proportional/keyboard layout acceptance is pending. Scrolling follows the corresponding heading positions in either pane. Section collapse retains its literal heading and replaces the hidden source body with an ellipsis; nested choices remain independent. Find temporarily expands the source, then restores prior folds on close. Actual bidirectional heading/wheel/focus/fold/find/reload acceptance passes in native, published and both installed channels on `2639e2d`; raw-heading parity audit remains open.
|
||||
- **View → Frontmatter:** hide leading YAML by default, show an escaped metadata table, or render the block as Markdown. The mode is saved and applied to reloads.
|
||||
- **View:** choose the light, dark, or system shell theme; turn the startup splash and the
|
||||
startup update check on or off. Choices are saved immediately.
|
||||
- **Help → Activity log:** a live view of the app's log, with an errors-only filter and a
|
||||
shortcut to the log folder.
|
||||
- **Help → View on GitHub / Submit an issue… / Community support…:** source, bug/feature templates and Discussions for the Windows application.
|
||||
- **Help → Check for updates** and **Help → About**; About → Contributions credits Darin's original Mac app with repository, website and license links; Components links every restored application dependency, with development/test tools acknowledged separately.
|
||||
| Edition | Choose it for | Package |
|
||||
| --- | --- | --- |
|
||||
| Stable | Everyday reading | `markdownviewr-windows-stable-Setup.exe` |
|
||||
| Development preview | Trying upcoming changes | `markdownviewr-windows-dev-Setup.exe` |
|
||||
| Portable | Running without installation | `markdownviewr-windows-stable-Portable.zip` |
|
||||
|
||||
Settings and logs live in `%LOCALAPPDATA%\markdownviewr-windows`. Set the data-folder environment
|
||||
variable the app reports in its log (the app id in capitals, plus `_DATA_DIR`) to use a
|
||||
different folder, for example a portable one.
|
||||
Once available, download a package from [Releases](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/releases). Run Setup for a per-user installation without administrator rights, or extract the portable ZIP before launching the app.
|
||||
|
||||
## Building from source
|
||||
Installed editions check for updates through **Help → Check for updates**. Stable and development editions keep separate settings and update channels, so they can coexist. Portable copies do not self-update.
|
||||
|
||||
Prerequisites:
|
||||
## Quick start
|
||||
|
||||
- Windows 10 version 1809 or later, x64 or ARM64
|
||||
- Microsoft Edge WebView2 evergreen Runtime
|
||||
- .NET 10 SDK (the feature band is pinned by `global.json`)
|
||||
- Optionally Visual Studio 2026 (Windows App SDK workload) or Rider
|
||||
1. Choose **File → Open** or press **Ctrl+O** and select your Markdown file.
|
||||
2. Use **Theme** to choose a document palette, **Contents** to navigate, and **Source** to inspect the Markdown.
|
||||
3. Save changes in your editor; the viewer refreshes automatically.
|
||||
4. Choose **Print** in the toolbar to print or create a PDF.
|
||||
|
||||
```powershell
|
||||
# Once after generation, create and commit the NuGet locks locally:
|
||||
# dotnet restore MarkdownViewr.Windows.slnx -p:Platform=x64
|
||||
dotnet restore MarkdownViewr.Windows.slnx -p:Platform=x64 --locked-mode
|
||||
dotnet build MarkdownViewr.Windows.slnx -p:Platform=x64 -warnaserror
|
||||
dotnet test MarkdownViewr.Windows.slnx -p:Platform=x64 --no-build --filter "FullyQualifiedName!~UiTests"
|
||||
dotnet test tests/MarkdownViewr.Windows.UiTests --no-build # launches the app on the desktop
|
||||
```
|
||||
To open Markdown files in the viewer by default, use an installed copy and choose **File → Settings → General → Choose default file types**. Select MarkdownViewr in Windows Default Apps for your preferred extensions. Windows asks you to make that choice; installation preserves existing defaults.
|
||||
|
||||
Package versions are declared in `Directory.Packages.props` and locked in each project's
|
||||
`packages.lock.json`. [CONTRIBUTING.md](CONTRIBUTING.md) has the full local workflow,
|
||||
including the coverage gate and the format check that CI runs.
|
||||
See the [user guide](docs/user-guide.md) for settings, shortcuts, printing, and troubleshooting.
|
||||
|
||||
## Verifying a release
|
||||
## Help and feedback
|
||||
|
||||
Every release asset is listed in `SHA256SUMS` and has a build-provenance attestation
|
||||
signed by the KofTwentyTwo release workflow:
|
||||
Use **Help → Community support** for questions and **Help → Submit an issue** for bugs or feature requests. You can also visit [Discussions](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/discussions) or [Issues](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/issues) directly.
|
||||
|
||||
```powershell
|
||||
# Integrity: the file matches the published checksum
|
||||
(Get-FileHash .\markdownviewr-windows-stable-Setup.exe -Algorithm SHA256).Hash # compare to SHA256SUMS
|
||||
For a bug report, include the version from **Help → About**, your Windows version, and steps to reproduce. Remove private information from logs and screenshots. Report security vulnerabilities privately using [SECURITY.md](SECURITY.md).
|
||||
|
||||
# Origin: built by the KofTwentyTwo release workflow from this repository
|
||||
gh attestation verify .\markdownviewr-windows-stable-Setup.exe --repo KofTwentyTwo/MarkdownViewr.Windows --signer-repo KofTwentyTwo/standards
|
||||
## Developers and contributors
|
||||
|
||||
# Publisher: Authenticode signature (once code signing is enabled; see SECURITY.md)
|
||||
Get-AuthenticodeSignature .\markdownviewr-windows-stable-Setup.exe | Format-List Status, SignerCertificate
|
||||
```
|
||||
Want to help? Start with [CONTRIBUTING.md](CONTRIBUTING.md). Build commands, tests, architecture, and release verification are in [DEVELOPERS.md](DEVELOPERS.md).
|
||||
|
||||
## Support
|
||||
This is a Product-tier project adopting the [KofTwentyTwo standards](https://github.com/KofTwentyTwo/standards), built with AppKit and WinUI 3. OpenSSF enrollment is active; registration does not mean a passing badge has been earned.
|
||||
|
||||
The latest minor release receives fixes; see [SECURITY.md](SECURITY.md#supported-versions)
|
||||
for the full support policy.
|
||||
## Credits and license
|
||||
|
||||
## Security
|
||||
Based on [Darin Kelkhoff's original macOS markdownViewr](https://github.com/darinkelkhoff/markdownViewr). Visit [Darin's website](https://kelkhoff.com/). The Windows app also credits the open-source libraries it uses in **Help → About → Components**.
|
||||
|
||||
Report vulnerabilities privately; see [SECURITY.md](SECURITY.md). The app's attack
|
||||
surface is described in its [threat model](docs/security/threat-model.md).
|
||||
|
||||
[Parser fuzzing](docs/security/fuzzing.md) records reproducible security properties
|
||||
and campaign budgets. [Best Practices enrollment](docs/security/best-practices.md)
|
||||
remains incomplete; no project badge or conformance is claimed.
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE). Copyright (c) 2026 James Maes.
|
||||
|
||||
This Windows application is based on [Darin Kelkhoff's macOS markdownViewr](https://github.com/darinkelkhoff/markdownViewr). Visit [Darin's website](https://kelkhoff.com/). The original MIT copyright/license and adapted resource notices are included in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md), distributed with the app.
|
||||
|
||||
The current review build uses native Settings pages for long theme/editor forms,
|
||||
with Back, Save and Cancel. Contents and Source start off in new windows unless
|
||||
changed under Settings → Advanced; toolbar toggles affect the current reader.
|
||||
Contents and Print have icon/text labels, with depth selection retained in the
|
||||
Contents pane. The footer shows the loaded file's modification time, marks failed
|
||||
reloads/stale files and offers Open folder. Disabled editor commands explain their
|
||||
configuration state. These owner-review changes have passing local build/core/
|
||||
adapter/style gates; current native/distributed acceptance remains pending.
|
||||
|
||||
Stable releases use `markdownviewr-windows`; prereleases use
|
||||
`markdownviewr-windows-dev` and show **MarkdownViewr (dev)**. Each installed edition
|
||||
has its own install directory, settings/recent files, activity logs and update
|
||||
channel. Local loose builds retain the stable identity. Edition selection reads
|
||||
the actual Velopack channel before activation or window services initialize.
|
||||
Current local identity tests pass; actual side-by-side install/update acceptance
|
||||
remains required before publication.
|
||||
|
||||
The icon uses a distinct white Markdown/reading mark on the navy rounded tile
|
||||
shared with gclo. AppKit BrandTool generates its vector and all nine ICO sizes:
|
||||
|
||||
```powershell
|
||||
brandtool --out src/MarkdownViewr.Windows/Assets/Brand --start '#1A2B4D' --end '#0C1836' --glyph 'M 144 328 V 184 L 208 260 L 272 184 V 328 M 344 184 V 328 M 312 296 L 344 328 L 376 296 M 144 380 H 376' --stroke 28
|
||||
```
|
||||
Free and open source under the [MIT License](LICENSE). Original-author and dependency notices are preserved in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
|
||||
+1
-1
@@ -74,7 +74,7 @@ payloads, using final-byte hashes and verified provenance. Follow the
|
||||
```
|
||||
|
||||
4. Watch the **release** workflow, then verify the release as described in the
|
||||
[README](../README.md#verifying-a-release).
|
||||
[developer guide](../DEVELOPERS.md#releases-and-verification).
|
||||
5. Open a pull request that bumps `VersionPrefix` in `Directory.Build.props`.
|
||||
|
||||
## When something fails
|
||||
|
||||
+25
-22
@@ -4,30 +4,33 @@ Updated: 2026-10-12
|
||||
|
||||
## Current release status - 2026-10-12
|
||||
|
||||
Owner explicitly authorizes publication and confirms review/resolved findings for
|
||||
standards PR31/e3aaed4, PR39/0f46568 and PR41/1e2179a. All are merged. The
|
||||
reproduced PSScriptAnalyzer metadata race is fixed without dropping rules/tests
|
||||
or deadlines: 20 fresh-process probes and every hosted signing gate pass.
|
||||
Standards1.1.0 is published immutably at93b1d6163a4c466ae443e98b62786fc4d80d33bd,
|
||||
releaseCI38275622522 green. All five asset attestations, checksums and exact
|
||||
reviewed builder/module/composite bytes verify; evidence remains in AppKit/
|
||||
artifacts/standards-1.1.0-93b1d61. Checklist40 shipping proof is prepared.
|
||||
Standards 1.1.0 is published immutably at
|
||||
93b1d6163a4c466ae443e98b62786fc4d80d33bd; release CI38275622522 succeeds.
|
||||
All five asset attestations, checksums, and reviewed builder bytes verify.
|
||||
Standards inventory PR36 is merged at089a94ac following genuine owner review.
|
||||
|
||||
The app's final delta enables signing with the published SHA and explicit six-file
|
||||
catalog. Nine preflight tests, actual protected-variable preflight and workflow
|
||||
syntax/online security pass. Tested application code remains321816c: current
|
||||
313d258 acceptance passes published111, stable/dev110 each with zero skips,
|
||||
actual updates/restarts, registrations, default preservation and coexistence.
|
||||
Local final installer/portable/update signatures and payload checks pass;
|
||||
production CI OIDC and 1.0/dev publication still need the release run.
|
||||
App signing caller/catalog b1dc874 passes every hosted check in CI38276579007.
|
||||
Actual application code remains321816c. Retained published111 and installed
|
||||
stable/dev110 TRXs each have zero failures/skips; update/restart receipts,
|
||||
registrations, preserved defaults, and coexistence verify. Core677 tests and
|
||||
100% measured core line coverage pass. Local representative final signing and
|
||||
distribution proof pass; production CI OIDC signing and publication remain pending.
|
||||
|
||||
Keep scope to publication: no redesign, new feature work or repeated unchanged
|
||||
acceptance runs. Owner previews/profiles remain untouched. Final app review record,
|
||||
actual Windows OpenSSF URL and prepared inventory PR36 review remain required.
|
||||
The process-only Scorecard assessment is explicit; no invented badge, reviewer,
|
||||
90-day history or vulnerability statement. Final caller/docs commit will run the
|
||||
required unchanged CI; avoid additional commits while it runs unless a real failure
|
||||
or required owner enrollment result changes the candidate.
|
||||
Owner explicitly requested a user-first product README, real screenshots, usage
|
||||
documentation, separate developer guide, and public repository presentation.
|
||||
Issue34 tracks that batch. Two actual isolated preview screenshots were captured
|
||||
after the owner reserved a clear desktop; no private documents or background apps
|
||||
are included. Original owner processes/profiles remain untouched.
|
||||
|
||||
OpenSSF Metal project15417 is registered for this Windows repository, initially
|
||||
18% complete after provider import. Actual URL and progress badge are recorded;
|
||||
no passing badge or completed operating-practice assessment is claimed.
|
||||
|
||||
Next: finish this documentation candidate, obtain genuine final-head app review
|
||||
record, pass required checks, apply/read back the planned fuzzing context, merge,
|
||||
and publish signed1.0.0-beta.1/dev plus1.0.0/stable with exact asset verification.
|
||||
Issue33 is the release checklist. No new features or repeated unchanged local
|
||||
acceptance are needed. Existing publication authorization remains valid.
|
||||
|
||||
## Azure configured and representative local signatures verified - 2026-10-12
|
||||
|
||||
|
||||
+16
-50
@@ -2,57 +2,23 @@
|
||||
|
||||
## Current release checklist
|
||||
|
||||
- [x] Build and launch the requested latest self-containedde70220 review with a fresh isolated profile; protectPID127248. Version1.0.0-dev; no production1.0 exists.
|
||||
- [x] Record owner-reported disabled editor ToolTip.IsOpen exception as bug#32; prepare the same attached-tooltip/loaded-target correction and physical-hover/log-error acceptance.
|
||||
- [x] Exact321816c CI38238385482 passes focused29, native/published111 and installed stable/dev110 each, zero failures/skips; actual hover case and lifecycle receipts pass. Corrected isolated local reviewPID48976 is open; production signing remains unproved.
|
||||
- [x] Exactde70220 CI38209503930 terminal success: core677/100%, native/published111, focused28, stable/dev110 each and fuzz9+2, zero skips; actual updates/restarts, coexistence/registration/default preservation pass.
|
||||
- [x] Remove temporary timing instrumentation and retain measured evidence; fresh final-head verification remains required with bug#32.
|
||||
- [ ] Obtain the genuine final-head review record required by configuration Apply as well as merging; add/read back only the planned Actions-bound fuzzing context, preserving existing policy.
|
||||
- [x] Correct the disabled-editor tooltip exception; accepted application code321816c.
|
||||
- [x] Final signing caller b1dc874 / CI38276579007 passes all hosted checks, including published111 and stable/dev110 acceptance each, zero failures/skips.
|
||||
- [x] Verify actual update/restart, registrations, preserved defaults, and channel coexistence receipts.
|
||||
- [x] Publish/verify standards1.1.0 signing builder and merge owner-reviewed inventory PR36.
|
||||
- [x] Verify Azure configuration and representative local final signing/distribution proof; existing gclo configuration preserved.
|
||||
- [x] Register Windows OpenSSF project15417 and record its real progress badge; passing assessment remains incomplete.
|
||||
- [x] Prepare user-first README, real light/source screenshots, user guide, DEVELOPERS.md, and current support/contribution links (#34).
|
||||
- [x] Verify final documentation: six Markdown files pass lint, all33 local links resolve, static conformance has no FAIL; clear-desktop screenshots are inspected.
|
||||
- [ ] Commit/push the documentation candidate and pass required exact-head hosted checks.
|
||||
- [ ] Obtain the genuine final-head maintainer review record; apply/read back only the planned Actions-bound fuzzing context.
|
||||
- [ ] Merge the application and complete release checklist#33.
|
||||
- [ ] Prove production CI OIDC signing, then publish1.0.0-beta.1/dev and1.0.0/stable.
|
||||
- [ ] Verify downloaded final signatures/publisher/trust/timestamps, hashes, SBOMs, and attestations.
|
||||
- [ ] Complete the evidence-backed OpenSSF provider assessment with the maintainer's actual operating-practice attestations.
|
||||
|
||||
- [x] Pushe6fd281 and verify hosted fuzz9/9 core+2/2 activation,677 core/100% lines, focused28 and full native111, zero skips; retain actual evidence.
|
||||
- [x] Exactd052 hosted core677/100%, focused28, native111 and fuzz9+2 pass; published picker cancellation passes, but110/111 hit600 seconds without assertion failure/final TRX. Installed lifecycle not reached.
|
||||
- [ ] Measure retained launch/slow-wait/closure/Appearance-PDF timings to diagnose aggregate published runtime versus a blocked final operation; preserve111 cases and every assertion/deadline. Remove temporary timings after verified resolution; required fuzz context remains unapplied.
|
||||
|
||||
- [x] Exact82256f3 CI38201379210 passes668 core/100% lines, focused28, native/published109 and installed108 per channel, zero skips; actual lifecycle artifacts/logs retained.
|
||||
- [x] Prepare current-standard assurance record, five seeded parser/property targets and honest unenrolled Best Practices assessment (#30/#31).
|
||||
- [x] Run local long campaigns:80000 core inputs plus minimized oracle regression,20000 activation envelopes,677 core tests/100% measured lines, zero-warning Release/format and23 setup tests.
|
||||
- [ ] Exact82256f3 CI38201379210 is terminal green; push the reviewed assurance/campaign delta; verify hosted fuzzing plus all native/published/installed gates and add/read back its required check.
|
||||
- [ ] Enroll this exact Windows public Product in Best Practices; use its real URL/README badge and maintainer-attested assessment. Do not approve an enrollment exception or fabricate passing criteria.
|
||||
|
||||
- [x] Exactb542dcd all-channel CI38197169201 passes native/published109/109, focused28/28 and installed stable/dev108/108 each, zero skips; actual TRXs/lifecycle JSON retained.
|
||||
- [x] Resolve full-review finding: prefix reserved COM/LPT superscript theme-export names;668 core tests/100% measured lines and format pass.
|
||||
- [x] Finish application-source review:105 C# files plus markup/project configuration and relevant CI/release/installed paths; blob inventory and precise scope retained. Settings theme/editor edits already use pages.
|
||||
- [ ] Push the reviewed filename correction/checkpoint and verify fresh exact-head hosted gates; complete production-signing/owner acceptance and genuine final-head maintainer assessment.
|
||||
|
||||
- [x] Exact4d34656 / CI38193736344 terminal success: focused27/27, native/published106/106, installed stable/dev105/105 each; actual authored-code/raw-heading browser and channel lifecycle cases pass, zero skips.
|
||||
- [x] Complete local-document link implementation through scoped native windows, with662 core/100% measured lines,10 actual filesystem tests and zero-warning Release/format.
|
||||
- [x] Exactb542 hosted proof: physical local-link/duplicate/watcher/junction-reload case,109 native/published and108 per installed channel pass; original cases/deadlines retained.
|
||||
|
||||
The detailed checkpoints below preserve historical tasks. This section supersedes
|
||||
old "prepared/not run" statuses where the completed evidence now proves acceptance.
|
||||
Full product scope remains in PRODUCT.md; unsigned fixtures are not release proof.
|
||||
|
||||
- [x] Exact9d5c0d1 / CI38188145397: core598/100% measured lines; focused26/26, native/published106/106, installed stable/dev105/105 each, zero failures/skips.
|
||||
- [x] Actual source colors through hover/focus/theme/reload/copy, fold/find/raw-heading provenance and physical bidirectional Contents synchronization pass in published and both installed editions (#10/#16/#27).
|
||||
- [x] Actual independent windows, multiple-file picker/cancel, recent files, editor file/folder launches, IPC/profile boundaries, reload/deletion/locked-save recovery and snapshot footer pass (#6/#11/#14/#26).
|
||||
- [x] Native toolbar/menu synchronization, narrowed overflow, Print handoff/cancellation, real PDF glyph/pixel/layout output, width/CSS and theme editing/transfer/cancellation/sibling persistence pass (#7/#12/#13/#18/#22/#23).
|
||||
- [x] General pane defaults/Contents controls, Printing Apply/Restore and sibling drafts, palette/default controls, About runtime credits/Contributions and startup settings pass (#19/#21/#24/#25).
|
||||
- [x] Actual AppKit updates/restarts, target hashes, five-extension registration lifecycle and simultaneous stable/dev isolation with sibling-preserving uninstall pass. Retain actual TRXs and coexisting-channels.json.
|
||||
- [x] Pushedc3c735e focused26/26 passes; inspected complete native theme-manager and Printing screenshots confirm the window now fits the hosted monitor.
|
||||
- [x] Exactc3c735e full native106/106 passes, zero skips, including independent whole-desktop containment; retained current-native-c3c735e.log.
|
||||
- [x] Exactc3c735e CI38190828814 terminal success: published106/106, installed stable/dev105/105 each, zero skips; actual registration/coexistence/update JSON and TRXs retained.
|
||||
- [x] Reproduce/correct authored inline-code extension corruption and raw visible-text/metadata parity;642 core tests/100% measured lines, zero-warning Release/format pass.
|
||||
- [ ] Push the renderer correction after the preceding terminal run and verify the extended actual browser case plus all native/published/installed suites.
|
||||
- [ ] Obtain owner acceptance of the toolbar, icon and native Settings layout, including Windows11 scaling. Actual user-selected Default Apps/Open With/Explorer behavior remains unverified; read-only status/registration tests do not replace it.
|
||||
- [ ] Complete remaining reference rendering/extension/image/link fidelity review. Preserve pinned document CSS and the explicit native-pane CSS boundary; representative tests do not certify arbitrary documents or CSS.
|
||||
- [x] Owner review and release authority supplied for standards signing31, reference correction39 and analyzer fix41; all merged and builder1.1.0 published.
|
||||
- [ ] Obtain the prepared inventory PR36 human review for registration. AppKit-only tooling license32 and shared Help AppKit29/windows-app-template4 remain separate follow-ups.
|
||||
- [x] Standards1.1.0 is actually published/verified at93b1d616; final caller enables signing and its required six-file catalog, retaining fail-closed verification.
|
||||
- [x] Authenticated Azure readback verifies actual subscription/tenant, East US endpoint, Active releases/PublicTrust profile and full James Maes subject. Separate secretless CI identity, exact immutable release-environment trust, profile-scoped signer role and all seven protected release variables are configured/read back; existing gclo setup preserved.
|
||||
- [x] Local representative321816c six-binary signing test passes SignTool /pa /all /v and strict SHA256/publisher/trust/timestamp checks; owner previews untouched.
|
||||
- [ ] Prove the new CI identity through the protected release job; verify final installer/archive signatures after adopting the published reviewed builder.
|
||||
- [ ] Obtain genuine final-head maintainer review acknowledgement, complete required checks and merge the application.
|
||||
- [ ] Publish signed stable1.0/dev releases only after exact shipped binaries/installers verify publisher/trust/SHA256/RFC3161 timestamps; retain final checksums/metadata and installed acceptance.
|
||||
The historical checkpoints below retain previous evidence and superseded tasks.
|
||||
Original owner preview processes/profiles must remain untouched.
|
||||
|
||||
## Historical checkpoints
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 113 KiB |
@@ -2,8 +2,8 @@
|
||||
"schemaVersion": 1,
|
||||
"badge": {
|
||||
"applicability": "required",
|
||||
"reason": "MarkdownViewr.Windows is a public open-source Product. Enrollment and maintainer attestation are required; no real project ID has been established.",
|
||||
"projectUrl": null,
|
||||
"reason": "Public open-source Product enrolled as project 15417. Evidence-backed maintainer assessment remains required; enrollment does not establish passing status.",
|
||||
"projectUrl": "https://www.bestpractices.dev/en/projects/15417",
|
||||
"evidence": "docs/security/best-practices.md"
|
||||
},
|
||||
"fuzzing": {
|
||||
|
||||
@@ -1,40 +1,30 @@
|
||||
# OpenSSF Best Practices assessment
|
||||
|
||||
## Scope and ownership
|
||||
## Scope and enrollment
|
||||
|
||||
MarkdownViewr.Windows is a public open-source Product; K22-REPO-12 requires real
|
||||
enrollment and an evidence-backed assessment. This is the Windows repository,
|
||||
not Darin Kelkhoff's original macOS project. Maintainer: @KofTwentyTwo (James Maes).
|
||||
Prepared 2026-10-11 by Codex; maintainer/provider assessment has not been completed.
|
||||
Reassess by 2027-01-09, and before each MINOR/MAJOR release.
|
||||
MarkdownViewr.Windows is a public open-source Product; K22-REPO-12 requires real enrollment and an evidence-backed assessment. Maintainer: @KofTwentyTwo (James Maes). This entry covers the Windows repository, separately from Darin Kelkhoff's macOS project.
|
||||
|
||||
No project URL/ID is established. `assurance.json` correctly records required
|
||||
scope and a null project URL; the README has no invented Best Practices badge.
|
||||
Enrollment remains a failing requirement, not an exception or passing badge.
|
||||
Registered on 2026-10-12 as [project 15417](https://www.bestpractices.dev/en/projects/15417), with repository and home page both pointing to this GitHub repository. The Metal passing assessment was initially **18% complete** after provider import. Registration and a progress badge do not establish passing status.
|
||||
|
||||
## Evidence prepared for enrollment
|
||||
Reassess by 2027-01-10 and before each MINOR/MAJOR release. The maintainer must confirm actual operating practices and incomplete criteria.
|
||||
|
||||
| Area | Repository evidence and precise limit |
|
||||
## Evidence
|
||||
|
||||
| Area | Evidence and limits |
|
||||
| --- | --- |
|
||||
| Identity/license | README, LICENSE (MIT), CONTRIBUTING, public source and retained Darin/vendor notices. Shared inventory entry is proposed in standards PR #36, not merged. |
|
||||
| Documentation/change control | PRODUCT/ADRs, usage/build/replay commands, linked feature/bug issues and signed/DCO topic commits in PR #3. Final-head maintainer acknowledgement remains required. |
|
||||
| Security reporting | SECURITY.md supplies private GitHub vulnerability reporting, response targets and supported-version policy. Threat model records browser/filesystem/IPC/editor/update boundaries. Maintainer must attest actual operating practices. |
|
||||
| Build/test | Locked dependencies, zero-warning build, formatter/analyzers, core coverage, hosted native/published/installed acceptance and the prepared parser fuzzing gate. Unsigned fixture tests do not prove signatures or arbitrary document coverage. |
|
||||
| Supply chain | Full-SHA action pins, dependency review/audit, secret/workflow/CodeQL scans, linked component credits and bundled license notices. |
|
||||
| Releases/crypto | Stable/dev update isolation and byte checks pass synthetic installed acceptance. Real Azure signing authority, final shipped signature/timestamp verification and signed 1.0/dev releases remain incomplete. |
|
||||
| Governance | Single-maintainer policy is explicit. Automated review does not constitute independent human review; every current-head finding/acknowledgement must be genuine. |
|
||||
| Identity/license | README, MIT LICENSE, CONTRIBUTING, retained author/vendor notices; standards inventory merged in PR #36. |
|
||||
| Documentation/change control | User/developer guides, PRODUCT/ADRs, linked issues, signed/DCO commits in app PR #3. Final-head human acknowledgement remains required. |
|
||||
| Security reporting | SECURITY.md, private GitHub reporting, response/support policy, and threat model. Actual response practices require maintainer attestation. |
|
||||
| Build/test | Locked restore, zero-warning build, analyzers, 100% measured core coverage, parser campaigns, native/published/installed acceptance. Tests do not certify arbitrary documents. |
|
||||
| Supply chain | Full-SHA action pins, dependency review/audit, secret/workflow/CodeQL scans, component credits, bundled notices. |
|
||||
| Releases/crypto | Current installed fixture updates/coexistence pass. Local signing/distribution proof passes; production CI OIDC signing and published stable/dev assets remain pending. |
|
||||
| Governance | Single-maintainer policy is explicit. Automated review is not independent human review; acknowledgements must be genuine. |
|
||||
|
||||
## Maintainer actions
|
||||
## Remaining assessment actions
|
||||
|
||||
1. Sign into [OpenSSF Best Practices](https://www.bestpractices.dev/en) and create
|
||||
the project for `https://github.com/KofTwentyTwo/MarkdownViewr.Windows`, named
|
||||
MarkdownViewr for Windows. Preserve any existing project if enrollment already
|
||||
exists; verify its repository identity instead of creating a duplicate.
|
||||
2. Supply the actual returned project URL/ID. Set `badge.projectUrl` in
|
||||
[assurance.json](assurance.json), then link its real badge from README.
|
||||
3. Review every current criterion against the evidence above and actual operations.
|
||||
Record incomplete items honestly; registration alone is not a passing assessment.
|
||||
Update this document with the assessed URL/date and remaining criterion actions.
|
||||
4. Resolve signing/release and other required criteria before claiming conformance.
|
||||
An enrollment obstacle needs a reviewed dated standards exception; no exception
|
||||
is approved by this document or by an agent posting a proposed draft.
|
||||
1. Review each provider criterion against repository evidence and actual operations; mark incomplete items honestly.
|
||||
2. Confirm security-response and review practices personally.
|
||||
3. Complete production release verification before claiming release-related criteria.
|
||||
4. Save the evidence-backed assessment on the provider, with any required agreement confirmed by the maintainer.
|
||||
|
||||
No passing badge, approved exception, independent reviewer, or completed production release is claimed by this document.
|
||||
@@ -0,0 +1,77 @@
|
||||
# Using MarkdownViewr
|
||||
|
||||
## Open and read a document
|
||||
|
||||
Choose **File → Open** or press **Ctrl+O**. You can open multiple documents in separate windows, return to recent files from the File menu, or open a file through Explorer after installing and selecting its association.
|
||||
|
||||
MarkdownViewr is a reader. Use **Open in editor** to edit a document in your configured external editor; the Source pane is read-only. Configure named editors in **File → Settings → Editors**. A disabled editor command explains what is missing when you hover over it.
|
||||
|
||||
## Contents, source, and search
|
||||
|
||||
- **Contents** shows document headings. Choose the heading depth in the pane, select a heading to jump, or collapse sections to concentrate on the rest.
|
||||
- **Source** shows highlighted Markdown beside the rendered document. Each window starts with an equal split; drag the divider to resize. Focus the divider and use Left/Right, or Home to restore equal panes.
|
||||
- **Ctrl+F** searches the document and source. Enter moves to the next match; Shift+Enter moves back; Escape closes search.
|
||||
- Use the zoom buttons, **Ctrl++**, **Ctrl+-**, or **Ctrl+0** to adjust reading size or restore 100%.
|
||||
|
||||
Contents and Source are hidden in new windows by default. Set independent defaults in **Settings → General**; toolbar toggles affect the current window.
|
||||
|
||||
## Choose your appearance
|
||||
|
||||
The document palette and application light/dark appearance are separate choices. Use **Theme** in the toolbar to select a document palette. Use the View menu for app appearance and Markdown extension/frontmatter options.
|
||||
|
||||
**File → Settings** provides these pages:
|
||||
|
||||
| Page | Controls |
|
||||
| --- | --- |
|
||||
| General | Reading width and custom CSS, Contents presentation, new-window pane defaults, and default file types |
|
||||
| Document themes | Palette selection, editing, management, and JSON import/export |
|
||||
| Editors | Named external editors, order, and document/folder launch preferences |
|
||||
| Printing | Saved print defaults |
|
||||
| Advanced | Startup splash, splash duration, and startup update checks |
|
||||
|
||||
Immediate settings save as you change them. Custom CSS uses **Apply**; theme/editor drafts use **Save** or **Cancel**. The Printing page provides explicit save/restore actions. Theme editing is intended for your own trusted preferences.
|
||||
|
||||
## Follow file changes
|
||||
|
||||
Saving a file in another app refreshes both the rendered document and source automatically, while retaining your relative reading position. Replacement saves are supported.
|
||||
|
||||
If a file is deleted or cannot be read, the last loaded document stays visible. The footer indicates a stale snapshot or failed reload. Restore the file or choose **File → Reload** to retry. The footer also shows the loaded snapshot's modification time and **Open folder** for Explorer.
|
||||
|
||||
## Print or save a PDF
|
||||
|
||||
1. Select **Print** in the toolbar, **File → Print**, or **Ctrl+P**.
|
||||
2. Choose print theme, image/background options, font scaling, width, borders, and page padding.
|
||||
3. Select **Print...** to hand the document to the system print dialog, or **Save PDF...** and choose a destination.
|
||||
4. For PDF output, enable the optional actions to open the PDF or its containing folder.
|
||||
|
||||
Cancelling leaves the reading view unchanged. Use **Settings → Printing** to save defaults for later jobs.
|
||||
|
||||
## Make it your default Markdown reader
|
||||
|
||||
This requires an installed edition; a portable copy does not register default-file choices.
|
||||
|
||||
1. Open **File → Settings → General → Choose default file types**.
|
||||
2. In Windows Default Apps, select MarkdownViewr and assign the extensions you want.
|
||||
3. Try opening a Markdown file from Explorer.
|
||||
|
||||
Supported choices are `.md`, `.markdown`, `.mdown`, and `.mkd`; `.txt` is optional. Depending on Windows version, the button opens this app's page or the general Default Apps page. You can also right-click a file, choose **Open with**, and select the installed viewer.
|
||||
|
||||
The installer preserves your current defaults. Windows requires you to choose the replacement.
|
||||
|
||||
## Updates and local data
|
||||
|
||||
Installed stable and development editions update within their own channels using **Help → Check for updates**. They have separate settings, recent files, and logs. Portable copies require a fresh download.
|
||||
|
||||
Settings and logs are stored locally under `%LOCALAPPDATA%\markdownviewr-windows` or `%LOCALAPPDATA%\markdownviewr-windows-dev`. **Help → Activity log** opens the log viewer and provides a shortcut to its folder.
|
||||
|
||||
Documents are rendered locally. Authored scripts and remote images are blocked; local images must stay within the document folder. Following an external link is a deliberate action.
|
||||
|
||||
## Troubleshooting and support
|
||||
|
||||
- **The app cannot display a document:** check that the file still exists and is readable, then try **File → Reload**.
|
||||
- **A remote image is absent:** remote image loading is blocked by the reader's document policy.
|
||||
- **Open in editor is disabled:** hover for the reason, then configure an installed editor in Settings.
|
||||
- **The viewer is not a default option:** use Setup rather than a portable copy, then reopen Windows Default Apps.
|
||||
- **The app does not start:** confirm Microsoft Edge WebView2 Runtime is installed and inspect the activity logs if available.
|
||||
|
||||
For help, use [Discussions](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/discussions). Report reproducible problems through [Issues](https://github.com/KofTwentyTwo/MarkdownViewr.Windows/issues/new/choose), including **Help → About** version, Windows version, and relevant sanitized logs. Report vulnerabilities privately using [SECURITY.md](../SECURITY.md).
|
||||
Reference in new issue
Block a user