search

knative / docs

User documentation for Knative components.
https://knative.dev/docs/
Other
4.56k stars 1.23k forks source link

How to build the docs website (knative.dev) locally? #1239

Closed aliok closed 4 years ago

aliok commented 5 years ago

Describe the change you'd like to see Instructions on how to build the docs locally.

Additional context I noticed some formatting errors and wanted to debug them but I can't debug without being able to build the docs locally.

samodell commented 5 years ago

Hey @aliok -- do you mean building the docs to see how they'll appear on the knative.dev website? If that's the case, @RichieEscarez can help with that.

It's true that the markdown rendering on the website isn't perfectly in sync with GitHub's own markdown rendering; I have seen some formatting issues. We'd love for you to look into those.

aliok commented 5 years ago

Hey @aliok -- do you mean building the docs to see how they'll appear on the knative.dev website? If that's the case, @RichieEscarez can help with that.

@samodell yes, exactly. Some Markdown content is rendered strange and I wanted to debug them locally. But I don't know what kind of set up is used here.

aliok commented 5 years ago

Ok, now I found it. https://github.com/knative/website is building it.

I will send a PR to note this in the docs repo.

RichieEscarez commented 5 years ago

Status: I will open a PR for this some time tomorrow (sorry, our team has been out of office the first part of the week at a workshop so playing catch up now).

@sebgoa @aliok For the interim, the local build steps are generally:

  1. Install and setup Hugo local server: https://gohugo.io/getting-started/quick-start/
  2. Meet Docsy requirements: https://github.com/google/docsy-example/blob/master/content/en/docs/Getting%20started/_index.md
  3. Clone knative/website
  4. Meet Hugo's expectation that all content lives under a single root directory. Either:
    • clone knative/docs into the content/en folder
    • clone knative/docs elsewhere and then create a symlink to there from the content/en folder (of knative/website)
  5. Run hugo server from the root of knative/website and open your localhost

There is a little more to this (small details) but Ill consolidate all these steps and the missing detail into a single page.

RichieEscarez commented 5 years ago

Instructions and the new local build script are here: https://github.com/knative/website/pull/72/files

(a formal instruction page might come after the 0.8 release)

aliok commented 5 years ago

Thanks @RichieEscarez Didn't have a chance to verify the instructions and the script but I am ok with resolving this ticket. If I have a chance, I would write here regardless.

aliok commented 4 years ago

@RichieEscarez just had a chance to give the script a try. It works great.

I guess we cannot have a README.md on the website repo as it would be rendered as well, right? Can we have a txt file that is not rendered?

Would be nice to see how to build the website quickly, instead of looking inside the script

RichieEscarez commented 4 years ago

That's great to hear @aliok. I will eventually add a README the knative/website repo. Other than the fact that the process seems to change from month to month as I fix or improve things, I do have other priorities right now. We are restructuring all of our content right now but after that I'll be able to document all these administration type steps.

knative-housekeeping-robot commented 4 years ago

Issues go stale after 90 days of inactivity. Mark the issue as fresh by adding the comment /remove-lifecycle stale. Stale issues rot after an additional 30 days of inactivity and eventually close. If this issue is safe to close now please do so by adding the comment /close.

Send feedback to Knative Productivity Slack channel or file an issue in knative/test-infra.

/lifecycle stale

knative-housekeeping-robot commented 4 years ago

Stale issues rot after 30 days of inactivity. Mark the issue as fresh by adding the comment /remove-lifecycle rotten. Rotten issues close after an additional 30 days of inactivity. If this issue is safe to close now please do so by adding the comment /close.

Send feedback to Knative Productivity Slack channel or file an issue in knative/test-infra.

/lifecycle rotten

knative-housekeeping-robot commented 4 years ago

Rotten issues close after 30 days of inactivity. Reopen the issue with /reopen. Mark the issue as fresh by adding the comment /remove-lifecycle rotten.

Send feedback to Knative Productivity Slack channel or file an issue in knative/test-infra.

/close

knative-prow-robot commented 4 years ago

@knative-housekeeping-robot: Closing this issue.

In response to [this](https://github.com/knative/docs/issues/1239#issuecomment-647118663): >Rotten issues close after 30 days of inactivity. >Reopen the issue with `/reopen`. >Mark the issue as fresh by adding the comment `/remove-lifecycle rotten`. > >Send feedback to [Knative Productivity Slack channel](https://knative.slack.com/messages/CCSNR4FCH) or file an issue in [knative/test-infra](https://github.com/knative/test-infra/issues/new). > >/close Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.