Hi @xhlulu thanks for the pull request :-). Doc tutorials need to have a header with information from jupytext and some meta-data about the tutorial. See for example the header of https://raw.githubusercontent.com/plotly/plotly.py/master/doc/python/line-and-scatter.md. I'm surprised that there is no header at all did you edit the file in the notebook? jupyter/jupytext should have created one.
For the header you can copy&paste from another md file, and edit the information in a text editor (like the title etc.). In which section of the doc should this tutorial appear? A new one maybe?

Thanks @emmanuelle for the review! I added your suggestions to the notebook. Here's an overview of what I also changed: "i split the knn into two notebooks; one for regression (didn't touch it further, just a placeholder notebook), and added 4 sections to the knn notebook. Now it has two "simple" sections that takes less than 20 lines, and 2 more "advanced vis" for 3D and splom viz"

Some things I am stuck on:

• In the header, I need to indicate a permalink, and a redirect_from. Is the permalink the url of the notebook? As for the redirect from, is it the URL of the section where the notebook is categorized?
• Do I need to manually create a "ML section" in some other files before the new section appears, or is it done automatically when I create a md notebook?
• Where should I store my new thumbnail?
• How can you create a new notebook such that it has an automatic header generated, and is in md format? what i'm currently is manually create a new md file, and then close it and reopen it and jupyter will load it as a notebook.

For the header, here's what it currently looks like: https://github.com/plotly/plotly.py/pull/2172/files/70f7131b939e4396b46405b02e42b3914c9bdfe7#

Good questions! @jdamiba shouls be able to steer you in the right direction :)

Some things I am stuck on:

• In the header, I need to indicate a permalink, and a redirect_from. Is the permalink the url of the notebook? As for the redirect from, is it the URL of the section where the notebook is categorized?
• Do I need to manually create a "ML section" in some other files before the new section appears, or is it done automatically when I create a md notebook?
• Where should I store my new thumbnail?
• How can you create a new notebook such that it has an automatic header generated, and is in md format? what i'm currently is manually create a new md file, and then close it and reopen it and jupyter will load it as a notebook.

For the header, here's what it currently looks like: https://github.com/plotly/plotly.py/pull/2172/files/70f7131b939e4396b46405b02e42b3914c9bdfe7#

The permalink determines the URL of the notebook. This is always a slugified version of the name, preceded by /python/.

So if the name of the notebook is Example Title then the permalink will be /python/example-title. If the name of the notebook is Another Example Title then the permalink will be /python/another-example-title.

The redirect_from is only necessary if you want the notebook to take over traffic from another notebook that is being deprecated. In this case you don't need to use it since you are creating new URLs.

You don't need to create the ML section, I took care of that in plotly/graphing-library-docs#9. Just make sure to set display_as: ai_ml. Posts that will go on the index page need to have page_type: example_index and order less than five. Posts with order greater than five need to have page_type: u-guide. You cannot have a post with order of exactly 5, that is reserved for the section index page.

Here are the instructions for uploading a thumbnail image. Once the image is uploaded, you set thumbnail: thumbnail/your-image-name.jpg.

Use images.plot.ly for adding new images. The password is in the Plotly 1Password Engineering Vault.
Log-in here: https://661924842005.signin.aws.amazon.com/console
From the Amazon Web Services Console select S3 (Scalable Storage in the Cloud) then select plotly-tutorials -> plotly-documentation -> thumbnail
Now from All Buckets /plotly-tutorials/plotly-documentation/thumbnail select the Actions dropdown and upload your .jpg file

I'm not sure how to create a new notebook with the right header- I would suggest just copy and pasting the header from another example and modifying it. Maybe @emmanuelle has a better idea? You can also try creating the notebook in Jupyter if you get the Jupytext extension.

Let me know if you have any other questions or if any of this wasn't clear!

@jdamiba Wow! Thank you for the super detailed answer! I'll be working on this friday/saturday. Just a question: does order start at 1 or 0? And if i understand correctly, we would be doing 0,1,2,3,4 for what we want to show on the landing page, then 6,7,8,... for everything else? I show never use 5?

Order actually starts at 1, so you want to use 1, 2, 3, and 4 for the pages you want to show up on the landing page, and 6, 7, 8, ..., N for the rest.

No page that you create in this repo should have order 5, as that is reserved for use by the category index page in the graphing-library-docs repo.

@emmanuelle thank you for all the suggestions! I just want to first draft out the other notebooks, then address your reviews :)

Moved to #2276