Skip to content

Improve Makefile commands w.r.t. auto-inserted doc links.#50

Merged
DanilaFe merged 6 commits intochapel-lang:mainfrom
DanilaFe:preview-with-links
Jan 22, 2026
Merged

Improve Makefile commands w.r.t. auto-inserted doc links.#50
DanilaFe merged 6 commits intochapel-lang:mainfrom
DanilaFe:preview-with-links

Conversation

@DanilaFe
Copy link
Contributor

@DanilaFe DanilaFe commented Jan 14, 2026

This addresses a discussion in which make preview didn't preview auto-inserted documentation links. Currently, the auto-inserted links are inserted as a post-processing step. This makes them incompatible with commands that allow hugo to continuously re-render the site and write the results to public. Moreover, I think we've identified two distinct modes of "preview":

  • A live preview, useful while you are editing the blog post. As you type your article, the blog changes to show you what your current text looks like in HTML.
  • A "staging preview", in which you render the post to see what it would look like on the final site. At this point, you're iterating much less, and want the result to be as close to the published version as possible.

For the first case, it makes sense to spawn a watching server, and skip post-processing. In the second case, we want to post-process, and so can't watch the filesystem. This has led me to separate the Makefile commands into make preview-links (high-fidelity pre-publication preview) and make watch (live iteration environment, aliasing the old make preview). For compatibility, I kept all existing command names as they were.

As discussed offline, make preview does not use relative links like make www, to avoid assuming the blog repo has access to the https://github.com/chapel-lang/chapel-www/ repo on the filesystem.

This PR also updates the README with these changes.

Reviewed by @bradcray -- thanks!

Signed-off-by: Danila Fedorin <daniel.fedorin@hpe.com>
Signed-off-by: Danila Fedorin <daniel.fedorin@hpe.com>
@bradcray
Copy link
Member

To avoid retraining users like myself, my strong preference here would be to not remove/rename existing Makefile targets, but to have the new preview mode be called something like make preview-www or make preview-links.

Signed-off-by: Danila Fedorin <daniel.fedorin@hpe.com>
Signed-off-by: Danila Fedorin <daniel.fedorin@hpe.com>
Signed-off-by: Danila Fedorin <daniel.fedorin@hpe.com>
Copy link
Member

@bradcray bradcray left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great to me Daniel, thanks! And thanks for updating the docs. Other than the small typo I noted, I think that the OP may be out-of-date w.r.t. what the final makefile command names are? Other than that, this is good to go.

README.md Outdated
> ```
>
> The post-processing steps are not currently compatible with live updates,
> which is why this option is not the default. The command also spawns
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you're missing "a" here in "spawns a server"

Signed-off-by: Danila Fedorin <daniel.fedorin@hpe.com>
@DanilaFe
Copy link
Contributor Author

Thanks Brad! I've updated the OP and fixed the typo. Planning to merge once the CI finishes its build.

@DanilaFe DanilaFe merged commit 53ac50b into chapel-lang:main Jan 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants