Creating article

[brucou]

Hello there. I enjoyed reading a few poet stories. I would like to try it out from writing my own stories. Concretely, I have an article here, which has not been published yet : https://github.com/brucou/movie-search-app/blob/specs-all/article/article.md . It is a rather long article. I would very much like to use the linking of text and code. I am unsure however how to do that. I follow TDD in the article, and there 4 iterations on an app in the beginning that I would like to showcase.

The URL of what I tried is here : https://poet.codes/e/rpqlKk4z8i1#uikit.css

There are several problems who stopped me :

• uikit.css is not there anymore (https://github.com/brucou/movie-search-app/blob/specs-S1/src/uikit.css)
• same goes for index.js
• but index.css seems to have been saved somehow. This might be to me mishandling the UI? But I clicked on save button everytime I created a new file.

Also, I wonder, I have 5 branches: https://github.com/brucou/movie-search-app/tree/specs-S1, https://github.com/brucou/movie-search-app/tree/specs-S2, https://github.com/brucou/movie-search-app/tree/specs-S4, https://github.com/brucou/movie-search-app/tree/specs-S8 and https://github.com/brucou/movie-search-app/tree/specs-all. How would I do to refer to those 5 branches of code in the same article? Is that even possible? Ideally I would like to show diff a-la-git between consecutive branches.

Last questions : how do you choose the entry point? Can it be js? html? or?

Many questions I know. It would be great though if I could use the extra functionalities provided by Poet.

[krasimir]

Hey @brucou,

First of all thank you for trying Poet. I spent some time making your app working in Poet and here's where I ended up https://poet.codes/e/XDXBxPVD8fK#index.js I did manage to get the data but there is no code that handles SEARCH_RESULTS_RECEIVED event.

Second, I know that Poet is poorly documented and I am planning to record series of videos explaining how it works. In the meantime here are some answers:

uikit.css is not there anymore same goes for index.js

I'm not sure what happened to you. When I opened your story it had two commits and in both those files were empty. Poet is not in any way connected to github and can't relate to content which is published there. If that is what you expect I have to say that it works like CodePen or Codesandbox. You have to manually copy/paste content and create the necessary files.

but index.css seems to have been saved somehow. This might be to me mishandling the UI? But I clicked on save button everytime I created a new file.

When you create a new file you don't have to click save. The existence of the file is saved automatically. What's not saved is your progress. It must be committed. But let me go into details here. When you create a file in Poet that file is part of the working tree. This means that if you switch between commits you may lose its content. Poet warns you if you try doing it but still it is possible. So, when you type something in your file and press Cmd+S or Ctrl+S your are saving to the working directory. The Save button that you are talking about is saving your changes to the current commit. Pretty much like git you may have many commits that represent the different states of your story. Once you click the Save button you are free to jump between commits because your progress now persist. (By jumping between commits I mean clicking on these two buttons Building robust, maintainable, testable user interfaces with state machines and ...)

Also, I wonder, I have 5 branches ...

Poet has no support of branches. Only commits. But you can simulate that. I mean even in Git you may think about the head of your branches as just different snapshots of your code. In Poet you can achieve the same thing by creating different commits. Just apply the code that you have in your first branch and when you are down click on "New commit" and apply the code from the second branch. Then save.

Ideally I would like to show diff a-la-git between consecutive branches.

There is no automatic way for doing this. You have to pretty much write/explain that with markdown (or in other words the content of the commit)

how do you choose the entry point? Can it be js? html? or?

Sorry about that. It is really hidden feature which I have to explain better. Probably in some way directly in the UI. You have to click the right button of the mouse on the file's tab. The entry point may be yes js, html or css. The entry point is almost always a js file. You don't need index.html because Poet already has that. It is empty and has <div id="output"></div> in it. If you want to add dependencies you are free to do it in the settings of your story. Here's what I did in the fork of your story: (You can go into this area if you click the hamburger menu in the upper right corner and choose "Editor") What happens when Poet runs your story is as follows:

• It fetches the dependencies listed in the settings
• It checks if there is an entry point. If it is a js file it runs it. If it is a html file it gets its content and adds it as a content of the already existing <div id="output"></div>. If it is a css file it does nothing.
• If there is no entry point it simply assumes that the currently selected file is the entry point.

Also notice that the imports work without ./ in front. The import statement in Poet works only with local for your Story files. And because everything is placed in just one level (there are no folders) you can just reference your file without ./.

---

Here are a few other things that you'll probably need:

If you want to link code and text you have to inject code by using the inject dropdown That is needed because otherwise Poet has no idea where the file is rendered and can't draw the junctions between the text and the code. Once you have the file injected you'll see something like {inject:helpers.js} in the text. Then you can select part of your code. That happens by creating a markdown link like [text]() and positioning the cursor on the place where the URL usually stays (between the curly brackets). Then go to the editor and select your code. In here https://poet.codes/e/XDXBxPVD8fK#helpers.js you can see how I did it.

To get your story published you have to go the "Story" settings in the upper right corner. There is no need to add h1 tag in your first commit. That is the job of the "Name" field. Also make sure that you check "Publish as a story at ...". Then your Story will appear on the poet.codes site. Something else which is also really important without which your commits are not visible. You have to enable each one of them by picking a position. This is important feature of Poet because it gives you the opportunity to save work in progress which is not published as part of your story. Also it gives you the ability to work on different parts of your article in different time and then just re-order them in the final published version.

I hope this helps and please don't hesitate to ask more questions here.

Here is your work as a Poet Story so far https://poet.codes/s/XDXBxPVD8fK/story

P.S. Poet works with UMD distributed libraries. While I was re-creating your app I had to:

• Bring react-hyperscript and hyperscript-helpers directly into the app because they are not distributed as UMD builds and can not be listed as dependencies in the "Editor" settings.
• Replace the superagent calls with just fetch. I didn't find a UMD build of superagent and fetch works just fine.

[brucou]

Thank you so much! I will have a look at it in detail tomorrow and come back with more comments. Just one thing - is the https://poet.codes/s/XDXBxPVD8fK/story means that the story is published? If that is the case I would like to unpublish it - the idea is that it is not indexed by google before the article is finished.

On 3/16/19, Krasimir Tsonev notifications@github.com wrote:

Hey @brucou,

First of all thank you for trying Poet. I spent some time making your app working in Poet and here's where I ended up https://poet.codes/e/XDXBxPVD8fK#index.js I did manage to get the data but there is no code that handles SEARCH_RESULTS_RECEIVED event.

Second, I know that Poet is poorly documented and I am planning to record series of videos explaining how it works. In the meantime here are some answers:

uikit.css is not there anymore same goes for index.js

I'm not sure what happened to you. When I opened your story it had two commits and in both those files were empty. Poet is not in any way connected to github and can't relate to content which is published there. If that is what you expect I have to say that it works like CodePen or Codesandbox. You have to manually copy/paste content and create the necessary files.

but index.css seems to have been saved somehow. This might be to me mishandling the UI? But I clicked on save button everytime I created a new file.

When you create a new file you don't have to click save. The existence of the file is saved automatically. What's not saved is your progress. It must be committed. But let me go into details here. When you create a file in Poet that file is part of the working tree. This means that if you switch between commits you may lose its content. Poet warns you if you try doing it but still it is possible. So, when you type something in your file and press Cmd+S or Ctrl+S your are saving to the working directory. The Save button that you are talking about is saving your changes to the current commit. Pretty much like git you may have many commits that represent the different states of your story. Once you click the Save button you are free to jump between commits because your progress now persist. (By jumping between commits I mean clicking on these two buttons Building robust, maintainable, testable user interfaces with state machines and ...)

Also, I wonder, I have 5 branches ...

Poet has no support of branches. Only commits. But you can simulate that. I mean even in Git you may think about the head of your branches as just different snapshots of your code. In Poet you can achieve the same thing by creating different commits. Just apply the code that you have in your first branch and when you are down click on "New commit" and apply the code from the second branch. Then save.

Ideally I would like to show diff a-la-git between consecutive branches.

There is no automatic way for doing this. You have to pretty much write/explain that with markdown (or in other words the content of the commit)

how do you choose the entry point? Can it be js? html? or?

Sorry about that. It is really hidden feature which I have to explain better. Probably in some way directly in the UI. You have to click the right button of the mouse on the file's tab. The entry point may be yes js, html or css. The entry point is almost always a js file. You don't need index.html because Poet already has that. It is empty and has <div id="output"></div> in it. If you want to add dependencies you are free to do it in the settings of your story. Here's what I did in the fork of your story: (You can go into this area if you click the hamburger menu in the upper right corner and choose "Editor") What happens when Poet runs your story is as follows:

• It fetches the dependencies listed in the settings
• It checks if there is an entry point. If it is a js file it runs it. If it is a html file it gets its content and adds it as a content of the already existing <div id="output"></div>. If it is a css file it does nothing.
• If there is no entry point it simply assumes that the currently selected file is the entry point.

Also notice that the imports work without ./ in front. The import statement in Poet works only with local for your Story files. And because everything is placed in just one level (there are no folders) you can just reference your file without ./.

---

Here are a few other things that you'll probably need:

If you want to link code and text you have to inject code by using the inject dropdown That is needed because otherwise Poet has no idea where the file is rendered and can't draw the junctions between the text and the code. Once you have the file injected you'll see something like {inject:helpers.js} in the text. Then you can select part of your code. That happens by creating a markdown link like [text]() and positioning the cursor on the place where the URL usually stays (between the curly brackets). Then go to the editor and select your code. In here https://poet.codes/e/XDXBxPVD8fK#helpers.js you can see how I did it.

To get your story published you have to go the "Story" settings in the upper right corner. There is no need to add h1 tag in your first commit. That is the job of the "Name" field. Also make sure that you check "Publish as a story at ...". Then your Story will appear on the poet.codes site. Something else which is also really important without which your commits are not visible. You have to enable each one of them by picking a position. This is important feature of Poet because it gives you the opportunity to save work in progress which is not published as part of your story. Also it gives you the ability to work on different parts of your article in different time and then just re-order them in the final published version.

I hope this helps and please don't hesitate to ask more questions here.

Here is your work as a Poet Story so far https://poet.codes/s/XDXBxPVD8fK/story

P.S. Poet works with UMD distributed libraries. While I was re-creating your app I had to:

• Bring react-hyperscript and hyperscript-helpers directly into the app because they are not distributed as UMD builds and can not be listed as dependencies in the "Editor" settings.
• Replace the superagent calls with just fetch. I didn't find a UMD build of superagent and fetch works just fine.

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/krasimir/poet.codes.feedback/issues/3#issuecomment-473499715

--

[brucou]

I also quickly wanted to share with you a resource I enjoyed about documentation : https://www.divio.com/blog/documentation/. These are the slides, you can also look at the video of the talk : https://www.youtube.com/watch?v=t4vKPhjcMZg. And if you have little time, one picture sums up the whole thing : https://divioag2017-live-e9fe0b8244c24280878375-8ae4759.divio-media.net/filer_public_thumbnails/filer_public/2f/b9/2fb95dd1-94be-4ad6-8180-7162ed6d5ecc/what_nobody_tells_you_about_documentation_extract_3001.png__1920x1080_q90_subsampling-2.png

Alright going to bed now.

[krasimir]

@brucou nope, the link above is only known by me and it doesn't appear anywhere. The public available URLs are the ones that you see:

• https://poet.codes/stories - list of all the published stories
• https://poet.codes/u/0Dw115rogf2 - your profile page.

In order to get something published you have to explicitly click "Publish as a story at ..."

Have in mind that seeing your profile page as you are logged in displays all the of your stories. Even the once that are not published. However, they are hidden for the others.

Also thanks for the links on the documentation. I'll check them.

[brucou]

Alright I think I understand what I can do. In which case, I'll write a different article focused on the TDD step by step. Will let you know when I am done or if I have questions.

On 3/16/19, Krasimir Tsonev notifications@github.com wrote:

@brucou nope, the link above is only known by me and it doesn't appear anywhere. The public available URLs are the ones that you see:

• https://poet.codes/stories - list of all the published stories
• https://poet.codes/u/0Dw115rogf2 - your profile page.

In order to get something published you have to explicitly click "Publish as a story at ..."

Have in mind that seeing your profile page as you are logged in displays all the of your stories. Even the once that are not published. However, they are hidden for the others.

Also thanks for the links on the documentation. I'll check them.

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/krasimir/poet.codes.feedback/issues/3#issuecomment-473562617

--