Add support for blog customization through YAML config #14487
Labels
Milestone
Comments
3 tasks
Florian3k
added a commit
that referenced
this issue
May 11, 2023
- Add input config, who allow to define the path import - Add output config, who allow to define the path destination - Add hidden, who allow to not generate the blog Should I add warnings? For example when the path is not found. If so, how do I test? Because the path is searched for _blog but it is not found so the assert that asks for no warnings does not work as in [this one](https://github.com/lampepfl/dotty/blob/d4a86000404cd3bb774025d48151c6311d6bc96d/scaladoc/test/dotty/tools/scaladoc/ReportingTest.scala#L73). Here is my proposal to add a blog configuration using a .yaml in the same place as the sidebar.yaml. This [feature](#14487) request is a bit old but I thought it would be interesting to create it to give a bit more flexibility to Scaladoc users. This first PR allows me to validate with you if this feature is good to implement and also to have some feedbacks I answer well to what is asked and that my code is relevant. So if it is the case, I will do the tests and the associated documentation. ### TO-DO list: - [x] First version of the code - [x] Add documentation Will be implemented in docs.scala-lang, [PR #2796](scala/docs.scala-lang#2796): *** ### Blog Configuration Documentation Blog configuration is an important aspect of any blog platform. In order to customize the configuration of a blog, it is often necessary to modify the default settings. In this document, we will explain how to change the default config of a blog documentation with a file blog.yaml. In order to modify the default settings of the blog documentation, users need to create a file named "blog.yaml" in the root directory of the blog. The file should contain the parameters that the user wants to change. For example, if a user wants to change the input directory to "my_posts", the output directory to "my_docs", and temporarily hide the blog, they can create a file with the following content: `blog.yaml:` ``` input: my_posts output: my_docs hidden: true ``` Parameters: The blog.yaml file is a configuration file that allows users to modify the default settings of their blog documentation. The following parameters can be configured in the blog.yaml file: input: This parameter specifies the directory where the markdown pages and other files will be taken for the blogs page. By default, this is set to the "_posts" folder in the "docs" directory of the blog. However, users can change this to any other directory in "docs". output: This parameter specifies the folder where the HTML pages will be generated. By default, this is set to the "blog" folder in the "target/docs" directory. However, users can change this to any other directory on "target/docs". hidden: This parameter allows users to hide or unhide the blog temporarily. By default, this is set to "false", which means that the blog is visible to all users. However, if a user wants to temporarily hide the blog, they can set this parameter to "true". This can be useful if the user wants to make some changes to the blog and doesn't want anyone to see the changes until they are ready. Once the file is created, the user needs to save it in the root directory of the blog. The next time the blog is built, the new settings will be applied. *** - [x] Add tests ## Example (Success) ### Code & Input <img width="328" alt="Screenshot 2023-04-06 at 14 41 47" src="https://user-images.githubusercontent.com/44496264/230382241-9433d641-03ec-4495-8fd2-81fa6ce3bc17.png"> <img width="329" alt="Screenshot 2023-04-06 at 14 41 58" src="https://user-images.githubusercontent.com/44496264/230382414-7876c601-b1f0-498f-85e1-71ecc500cf09.png"> ### Result <img width="326" alt="Screenshot 2023-04-06 at 14 42 09" src="https://user-images.githubusercontent.com/44496264/230382463-9fe234ac-3fd0-4d56-a04c-6f6deb01a308.png"> ## First example (Hidden) ### Code <img width="254" alt="Screenshot 2023-04-06 at 14 46 27" src="https://user-images.githubusercontent.com/44496264/230382770-7aabf9a2-e46f-429d-b1c9-97892072349a.png"> ### Result <img width="335" alt="Screenshot 2023-04-06 at 14 42 36" src="https://user-images.githubusercontent.com/44496264/230383192-05e0187f-5ecf-4bd9-8697-122093577d43.png"> <img width="316" alt="Screenshot 2023-04-06 at 14 42 47" src="https://user-images.githubusercontent.com/44496264/230382928-8130cddd-f8dd-4b43-bee1-15129af308c8.png"> ## Example (Error) <img width="316" alt="Screenshot 2023-04-06 at 14 43 03" src="https://user-images.githubusercontent.com/44496264/230383219-ff6844e2-47c5-40d6-9056-a8ab1dc6f8e6.png"> <img width="945" alt="Screenshot 2023-04-06 at 14 43 14" src="https://user-images.githubusercontent.com/44496264/230383236-2ee07f63-640c-4bc1-a3b1-e0785ff467e9.png"> Fixes: #14487
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Right now, if the
_blogdirectory exists in siteroot we always render Blog.We might want to be able to customize whether the Blog should be rendered, the input and output directory via YAML configuration.
The text was updated successfully, but these errors were encountered: