right now the HTML filename has, like, two possible formulas:

• match md filename exactly including folders
• convert / into - (flatten folder structure)

It would be great to add at least one more for using just the leaf filename (omit folders). Maybe other formulas too if any ideas come up.

Right now the link checker just reads the config file and checks the output directory regardless of what's there. Also, it reports "success" if said directory is empty or doesn't exist, when that case should probably be considered a failure.

It would be nice to support nonstandard output directories, like the -o option of dactyl_build, but -o is already an alias to --offline in the link checker so reusing that parameter would be a breaking change.

Another neat function would be a "virtual" link checker that keeps everything in memory, like the style checker, so you can specify a target to it instead of needing to run dactyl_build first. It would need to do some funny business to try and interpret whether static files would end up in the correct place when written out.

Some of the built-in filters rely on CSS that's not included in this repo. Update the examples/ include the sample css (and maybe have an assets folder?).

It would be great if Dactyl's style-checker included a spell-checker. The spellchecker should have the ability to modify the standard dictionary.

Right now if you don't want to use the default cover file for a target, you have to specify the --no_cover option on the commandline every time you build. It should be possible to add a no_cover flag to a target in the config file in case you don't want that target to use the default cover page. There are good reasons you may want to do this (maybe you want to include a special cover page for that target or you want something to appear before the table of contents that's normally provided by the cover page)

PyYAML is more or less unmaintained at this point and ruaml.yaml has some bugfixes and improvements.

Right now the link substitution behavior is kind of confusing and janky. It should be possible to implement it as a filter so it's not turned on by default.

Also, it would make sense to move the image substitutions to a specific field instead of just looking for top-level fields of page objects that happen to match target names. (The fact that it works as it does is a holdover from before Dactyl had real preprocessing functionality.)

probably related to the default PDF naming thing

See if there's a way to pass a Markdown-parsing function to the Jinja templates so that template blurbs can include Markdown syntax.

Might require a new Dactyl version or at least a Dactyl filter.

Jira ticket: https://ripplelabs.atlassian.net/browse/DOC-1577

Prince has a bug that causes links between different files to break when Dactyl builds them:

Normalise input filenames to avoid missing links on Windows. (ref, ref)

As long as that bug is on their roadmap and not done, linking between files in Dactyl-produced PDFs won't work.

However, it might be possible to work around this by changing the current working directory before running Prince so the paths don't have to include any slashes.

Fixes a bug with | characters appearing in tables

When I create a PDF using the filter: multicode_tabs, the content from the second (in this case last) tab is the only content displayed in the PDF output. The html output looks great.

the preprocessor and possibly the template processor should use StrictUndefined so they error out on missing fields.

Except if byass_errors is true of course

It would be cool to specify a whole folder of files in the config so that Dactyl would read the folder and expand that into a whole list of pages. Ideally you could specify a shell-like pattern, such as *.md, so you only get the files you want.

Maybe a special type of entry in the "pages" array:

  - __dactyl_type: pageset
    md_pattern: api_methods/*.md
    category: API Methods
    targets:
        - api-ref

The dactyl_build.py source is a mess of functions with too many arguments passed up and down and called in an unclear order.

It would be great to structure some of those types of information into classes and more strictly enforce type-safety for those classes.

Reorganizing the build pipeline would probably be helpful for #48 so that the "first pass" work could get done more effectively.

wkhtmltopdf seems like a good open-source option for people who don't want to buy a Prince license. It would be cool if Dactyl could be configured to use that or other HTML-to-PDF tools.

The CSS/HTML class name "devportal-callout" is a relic of the Ripple Dev Portal days. It's a breaking change for existing Ripple styles, which can be mitigated with a custom callouts filter, if #1 is fixed.

You can estimate the number of instances of passive voice by looking for instances of an auxiliary verb (am/are/were/being/is/was/be) followed by a word ending in "ed" or a pre-populated list of irregular past tense words. It's not foolproof, but it's enough to recognize when a sentence is overusing passive voice.

The Style Checker should report the proportion of sentences with passive voice detected in all pages. This can be an "information-only" detail by default. To make it involved in pass/fail, one would add goals for the proportion of detected passive voice instances per sentence. (Ideally the ratio is probably ~10%.) This would probably work similar to the readability scores in the style checker now.

It uses a mix of two-space and four-space indentations now, and that's gross.

if you're in a folder with a broken config file, or missing a custom filter, or something, dactyl_build -v errors out rather than doing what it's supposed to.

It shouldn't need to read the config file to output a version number.

I'm getting some weird errors from dactyl when trying to build the payment object schema. This is only when trying to publish the doc to the clients site using Jenkins.

I'm thinking dactyl is seeing two heading that start with the same object name, and it's not liking it.
latest error is this:

Previous error was this (different section of the page:

01:21:54 Uploading to ES: PUT https://HOSTNAME/ripplenet_payment_object-v1.1.4-supporting_info_schema/article/payment-object-additional-info.rmtinf.html
01:21:54 ES upload failed with error: '{"error":{"root_cause":[{"type":"mapper_parsing_exception","reason":"Could not dynamically add mapping for field [Amt.DscntApldAmt.Tp.Cd Known Values]. Existing mapping for [subheadings.Amt] must be of type object but found [text]."}],"type":"mapper_parsing_exception","reason":"Could not dynamically add mapping for field [Amt.DscntApldAmt.Tp.Cd Known Values]. Existing mapping for [subheadings.Amt] must be of type object but found [text]."},"status":400}'
01:21:54 Build step 'Execute shell' marked build as failure
01:21:54 Stopping Docker container after build completion
01:21:54 $ ssh-agent -k
01:21:54 unset SSH_AUTH_SOCK;
01:21:54 unset SSH_AGENT_PID;
01:21:54 echo Agent pid 19008 killed;
01:21:54 [ssh-agent] Stopped.

In each of these cases, dactyl hit a header that had previously started with the same word.

Examples of failed builds are in Jenkins
project: clients-doc-push, builds: 846-850
Happens with documents/network-rulebook/payment-object-addl-info/properties/rmtinf.md

There's a barf when dactyl hits the header

##### `LineDtls.Id.Tp.CdOrPrtry` Known Values

AS there is already a header

#### `LineDtls`

in the file that has been indexed

Many similar tools provide a built-in HTTP server so you can test the site locally with minimal setup. Dactyl could probably provide something very similar with Python's built-in simple HTTP server.

In some cases you may want to source images from multiple static path folders. Dactyl should support supplying an array of paths instead of just one content_static_path—each of the specified folders would get copied into the output folder (if -s is supplied) or the temp folder (for PDF)

Per XRPLF/xrpl-dev-portal#599 it looks like opening files without explicitly specifying the encoding is a problem because Windows defaults to latin-1 instead of utf-8.

Fixing this will require a system where I can reliably reproduce (can dig out a Windows laptop and see how it goes)...

For some documents, like the Network Rulebook, we may need to use numbered headings. I believe it's possible to do this by defining counters in the CSS, as exemplified here: https://gist.githubusercontent.com/joshbode/491ad0e678d456ea8ddc/raw/0921dbce72b1602958d4c0cc4b03a30768cd2cd8/numbered_headings.md

However, since we don't want to make that the default behavior, I think we'd want to make that an optional filter.

original jira ticket: https://ripplelabs.atlassian.net/browse/DOC-895

Maybe tie into the functionality to include specific lines of pages (experimental Dactyl feature already)

Original jira issue: https://ripplelabs.atlassian.net/browse/DOC-1164

Having suffered through some internet outages lately, I've come to appreciate how useful it would be to have an option that skips any docs that require external contents and does as much as it can offline (rather that waiting for connections to time out even if --bypass_errors is supplied)

Create a macro that enables us to pull in child pages (child page title link and blurb) that can be called from within a content block.

This will enable us to provide the autogenerated child page content - within a content block that provides a bit of content that includes markdown.

For an example of a page that could benefit from this macros, see https://developers.ripple.com/ledger-object-types.html.

Original jira ticket: https://ripplelabs.atlassian.net/browse/DOC-1564

Currently, Dactyl can parse frontmatter in Markdown files, but it does so late enough in the build pipeline that it can't use the metadata from the frontmatter for any useful purpose.

It would be great if you could use frontmatter to define as much as possible about pages, so the config file itself wouldn't have to be so large. This could also improve portability to/from other similar systems like Jekyll.

It would be nice to be able to pass in a list or file with arbitrary key-value vars to set on the target at runtime, so you can build better scripts around Dactyl

(This is done in a private branch of Ripple's docs-private repo, so it just needs to be ported and merged in.)

Similar to how the XREFs filter works, it should be possible to convert valid links between markdown source files into links to their corresponding HTML files.

This would dramatically improve the ease of importing existing (GitHub-compatible) markdown into Dactyl. It might even be a big enough deal that this filter should be enabled by default.

Config should let the user specify one (or more?) user filters directories. Dactyl should load filters from those directories preferentially, falling back upon the filters included in the core Dactyl package.

This way users can write their own filters that don't need to be contributed back to the Dactyl core.

I suggest you to add your generator to https://github.com/netlify/staticgen and https://github.com/bevry/staticsitegenerators-list

This is just suggestion. Feel free to close this ticket without any action.

Much of the current multi-locale stuff could probably be automated by making certain assumptions. This would take some investigation to make a proper plan first, especially one that would not be too much migration work, but here are some obvious ones:

• dactyl_build could compile .po files, if present, by calling Babel automatically
• Similarly, it could automatically extract {% trans %} strings to update the .pot file and .po files when run. If possible, it would be good to have a notification that new strings need to be translated.

Bigger challenges include:

• Support multiple languages in a single "target" with separate prefixes based on the language? Or build multiple "targets" (one per language) with a single command?
• Managing hyperlinks in MD content (including translated content) so that things go to the correct translation when using absolute URLs
• Maybe impossible, but some kind of assist for managing anchor links in translated content & links to/from untranslated pages.
• Guidance for managing translation age / updates. Maybe with Transifex? TBD.

People have noted that the .html extension on xrpl.org pages gives the impression that we are somewhat behind the times. Other comparable sites don't use such extensions and thus their use may reflect poorly on sites powered by Dactyl.

Here are some of the competitive examples:

• https://stripe.com/docs/stripe-js/elements/payment-request-button
• https://0x.org/wiki#Get-Started-With-Instant
• https://developers.libra.org/docs/my-first-transaction
• https://ethereum.org/use/#_1-use-an-application-built-on-ethereum

When a custom filter is not available, Dactyl tries loading it from all the custom filter paths, then falls back to the built-in filter path. Import errors on the last step aren't caught & can't be bypassed, but any case of a missing or inaccurate filter falls through to that case.

This gives a misleading error in a lot of cases and interferes with some other things too.

Dactyl's SCSS file is a monolith when it could be split into multiple smaller, modular files that are included to build the default CSS file.

Similar to Bootstrap's SCSS, Dactyl's files should make careful use of variables, !default statements, and dividing things up by topic. This would make it easier to build a custom SCSS file that leverages some elements of Dactyl's styles and can be updated with minimal effort.

As a bonus, make an NPM package for these so it's easier for other projects to load these files along with the Bootstrap source files.

Existing Dactyl sites use a JavaScript solution like highlight.js to provide syntax highlighting for code blocks. This runs in the browser, which means more to download and more to run on the client side, on every page view. For everything except API tools, syntax highlighting only has to be done once, at compile time.

The CodeHilite extension, which comes with Python-Markdown, can do this as part of the Markdown-parsing build step.

Then sites just need the appropriate CSS, with option to customize.

It would be nice to have both "critical" style violations and "advisory" style violations, or maybe even more levels. So the build would only break on critical errors, but you could take "suggestions" from the other guidelines.

Also it would be nice to be able to mark specific cases as exceptions to style rules.

If this works, we could add style checking to CI.

Original jira ticket: https://ripplelabs.atlassian.net/browse/DOC-372

similar to the absolute path bug fixed in v0.8.3, images whose src attribute is an absolute path won't be checked correctly and should be skipped rather than reporting an error.

It would be useful to be able to include only specific lines of a given code snippet rather than the entire file.

Here's an example of Sphinx's implementation of this: http://www.sphinx-doc.org/en/stable/markup/code.html#includes

Building a suite of docs can be pretty time-consuming. For example, building the XRPL dev portal takes ~25 seconds on my (relatively high-spec) desktop. There are probably some redundant steps or something that can be done to optimize the build so it runs a bit faster. Maybe some of it can also be parallelized on multi-core CPUs.

It would also be nice to improve the speed of the link checker, which is also probably something that can be parallelized.

Trying to import custom filters on Python 3.4.x and earlier fails in the wrong place because the import logic (see also: #23) tries to use importlib.util.module_from_spec which doesn't exist in versions before 3.5.

Dactyl should (at least) print a proper error/warning if you try to do this and maybe should allow you to skip over the custom filters or implement a v3.4-compatible import for them

Certain config options are meant to be local to an individual system, not to a project, but they're all defined in the same config file. This doesn't really make sense for a shared project that stores the config file in version control.

System-local config options should be configurable from a separate file that's stored in a userspace location such as $HOME/.config/dactyl/local.yml or something. Such options include:

• temporary_files_path
• prince_executable

By relying on the target.prefix field, the link checker should be able to check at least some absolute links whose start matches the prefix. This would improve link checking in sites with "pretty" URLs, which generally need to use absolute links extensively.

Images are currently generated as links in both HTML and PDFs. In the HTML, this is a nice feature because clicking on the image opens the image in a new browser tab. However, hovering over or clicking on the image in the PDF results in a weird experience because the "link" is to the local output file structure. See attached screenshot for an example.

Acceptance Criteria

• Clicking image in HMTL still opens new tab
• Image in PDF is non-clickable

Link to original JIRA issue: https://ripplelabs.atlassian.net/browse/DOC-1376

There are 3 types of template fields (6 total) but they're somewhat inconsistent

To be absolutely explicit, default_template and target/page. template would be best renamed html_template. The less dramatic change would be to change default_template to template or change the global pdf_template to default_pdf_template.

For simplicity's sake, the values passed to the templates and the values passed to the preprocessor should be as similar as possible. (There are cases where a field won't be present; for example, the preprocessor won't have the rendered HTML as a field.)

Mostly these are aleady OK but the preprocessor doesn't have access to all the good stuff the templates have, like current_time and so on