Rewrite directive need to clean up example

Between the confusion on the error message, how many arguments is needed?
The v2 documentation is not clear in the code example.

validate: adapting config using caddyfile: parsing caddyfile tokens for 'rewrite': /home/testing/Caddyfile:16 - Error during parsing: Wrong argument count or unexpected line ending after 'rewrite'

Hi Razor! Can you please fill out the template? It gives better context to understand what you’ve tried and allows us to give better guidance. Anyway, for starters, the docs for the rewrite directive of the Caddyfile can be found here.

I think it require at least a slash / on either arguments?

rewrite /a /b

The problem is if someone want to write regex, you would be lost at what and how to manage the errors or what is happening. It feel disconnected, you could understand Go language errors message right?

Could we still write the code that used to work for v1?

Then this docs isn’t clear.

To make it easier, it should contains before and after example/result and simplify the jargons for less well-versed developers.

Yes, I did read the doc for 6 hours and search all over the web, the doc need to be improved.

I don’t think we can really answer anything in this thread cause you didn’t fill out the issue template and didn’t ask any specific question.

I think you’ve just missed a few important sections in the docs that are causing a gap in your understanding. I’m not sure what that gap is because you weren’t specific about what’s going wrong.

We’re trying to help you but you aren’t letting us. The complaints are so far vague and not actionable. We simply need the answers to:

  • What does your config look like?
  • What did you try?
  • What exactly is the error you received?
  • Did the upgrade guide not help? (Note the part about rewrite). What is it lacking?
  • How did the documentation confuse you? As in, what misunderstanding did you pick up from the documentation?

Fine, if we concede the documentation is terrible, bad, and all kinds of awful. How would you improve it? We as maintainers are more familiar with ins-and-outs of the software, so we are better suited to write the documentation for it. But there’s a dilemma. To write documentation suitable for new-comers, we need to understand the mentality of someone who isn’t knees-deep into the software, but we can’t because that mentality has already left us. So if you need the help, you need to tell us what’s lacking. We need constructive feedback.

To make it easier, it should contains before and after example/result and simplify the jargons for less well-versed developers.

Oddly enough, there’s exactly that. You’re coming from v1 to v2. There’s an article in the docs called “Upgrading to Caddy 2”. Not only that, there’s a whole section on how to convert rewrites to v2 syntax. With example, bells, and whistles too. Now what are we missing?

2 Likes

Was planning to reply after a good sleep and have solved it after I found Caddy 2.1 changelog mentioned a single line of code.

  • What does your config look like?
    It’s a new configuration for WordPress, I have search some of the community contribute configuration is useful for my case.

  • What did you try?
    Now when I wanted to block /?author=1 which would reveal the username, using rewrite, redir in the docs appear to show only REST, are they applicable to Key=Pair?

  • What exactly is the error you received?
    I have missed a forward slash, and it mentioned wrong number of arguments, upon reaching the doc on rewrite, it should indicate we need to start with a forward slash. As a beginner’s point of view.

  • Did the upgrade guide not help? (Note the part about rewrite). What is it lacking?
    I didn’t aware there was a link on upgrade, it’s visually hard to spot in the docs and I never use V1 before, just join recently to start exploring V2.0.

  • How did the documentation confuse you? As in, what misunderstanding did you pick up from the documentation?

  • The font are quite big, I could use web browser to reduce website size to 90%, that’ll look better.
  • The doc menu is quite dim on the dark background (https://caddyserver.com/docs/) is quite different from majority of other sites that used white background.
  • The V1 menu structure is easier to discover with some directive is easily accessible than in V2, I have to use search field to reach that.

Thank you for coming back, but the answers, honestly, don’t help us understand your failed attempts nor did you share your successful attempt. Let me clarify…

What does your config look like?
It’s a new configuration for WordPress, I have search some of the community contribute configuration is useful for my case.

We’re trying to understand your config of Caddy, not your app. Did you not make an attempt at writing Caddy config, either in the form of JSON or Caddyfile? I’m trying to build a mental model of what the docs led you to believe about how Caddy does things, so we’d understand how to reword them or restructure them.

Anyway, for WordPress, there are 2 wiki posts covering how to configure Caddy to serve WordPress, here and here.

What did you try?
Now when I wanted to block /?author=1 which would reveal the username, using rewrite , redir in the docs appear to show only REST, are they applicable to Key=Pair?

You’re answering the question of what were you trying to achieve, but we would like to understand what did you try. In other words, what were your failed attempts. To achieve your end-goal, you probably need to take a look at the query matcher.

What exactly is the error you received?
I have missed a forward slash, and it mentioned wrong number of arguments, upon reaching the doc on rewrite, it should indicate we need to start with a forward slash. As a beginner’s point of view.

That’s your understanding of the issue. We’re trying to understand what was the error message you received. Perhaps the error message wasn’t clear enough. This is why we need to know what the input was (your attempted Caddy config) and what the error message that Caddy printed to you.

Did the upgrade guide not help? (Note the part about rewrite). What is it lacking?
I didn’t aware there was a link on upgrade, it’s visually hard to spot in the docs and I never use V1 before, just join recently to start exploring V2.0.

You asked if you could still use v1 syntax, so I assumed you were coming from v1. If you were comfortable with v1, the upgrade guide could help you reshape your understanding into v2’s expectation.

As for the doc design, we’ll see how the design can be improved. The theme of the docs pages follows your system, i.e. it’ll be dark themed if your system is configured to prefer dark.

If your hand is good at web design and front-end dev, the source code of the website is open-source and would love to have your contribution. Your experience of the challenges could be a good guide into knowing what to change.

Can you please share what worked for you? You know, for future generations.

3 Likes